<title>Animgraph</title> <cat>Model.Animation</cat> # What is the Animgraph ⤶ The Animgraph is a data-driven system for dynamically compositing keyframed & procedural skeletal animation, and for controlling when to transition between those compositions.⤶ ⤶ At its core, an animgraph is a tree of connected nodes. Each time the game updates, the graph is evaluated to calculate what the pose of the character should be for that frame. During the graph update, each node takes the animation poses from its children, performs operations (like blending or IK), and passes the resulting pose to its parent. The pose that gets passed to the root of the tree (the "Final Pose" node) is the one used for the character when it is rendered. ⤶ With Animgraph, game code is no longer directly telling the animation system which sequence to play, like in Source 1 games. Instead, the game code provides the graph with commands and context about the game environment, and it's up to the logic within the graph to determine what animations to play and how to play them. This allows the game code to focus on higher-level gameplay without having to micro-manage animation, and allows animators to create and iterate on better character performances without needing to understand code. ⤶ Put more simply, the "Player Animator" code is constantly sending parameters to the graph; these values represent various things, like current motion, which weapon is currently held, whether or not you are attacking, jumping, etc. and the graph is set up to "react" accordingly.⤶ ⤶ ⤶ The Animgraph works as a node based system. ⤶ you have your final pose node, and going left up to each next node in your node tree it will either change the pose, or direct the flow of the nodes to the next pose altering node, until it reaches the end and giving you your final pose for the given rendered frame. ⤶ <upload src="70317/8db7748b519423f.mp4" size="6417113" name="2023-06-27 20-56-09.mp4" />⤶ ⤶ The Animgraph has the advantage over code of ⤶ easily combining animations to create new poses, without the need to make a whole new animations just for it,⤶ or dealing with IK easily and so on, you can get easy amazing results using it.⤶ ⤶ ⤶ like dabbing while walking!⤶ ⤶ No need for a whole new animation, just use the legs for the walk, and upper body for dabbing⤶ just blend between the dabbing and walking to combine them into a new pose!⤶ ⤶ <upload src="70317/8db77499f0dfb8d.mp4" size="3413528" name="2023-06-27 21-02-26.mp4" />⤶ ⤶ ⤶ Although the Animgraph is used instead of game code to control the animations, you can still set various [parameters](https://wiki.facepunch.com/sbox/Animgraph_breakdown~edit#4parameters) every frame.⤶ nodes can reference these parameters to see how they should blend animation, what animations to use and much more.⤶ ⤶ ⤶ You can also choose to bypass this system altogether, either for performance or simplicity reasons. See this article: [Animations without animgraph](https://wiki.facepunch.com/sbox/Animations_without_Animgraph) <note>The Citizen animgraph is largely self-documented. Just open it up, and look around at comment boxes, and comments on individual nodes!</note> ⤶ <warning>The rest of the page is quite rough, follow at your own risk</warning>⤶ ⤶ ⤶ <warning>The rest of the page is quite rough, follow at your own risk</warning>⤶ # How does it work?⤶ ⤶ To put it straight, an animgraph allows you to change the outputted animation, mix animations, procedurally animate your model, using external inputs given via the code in your gamemode. ⤶ This may sound really confusing, but trust me, its not, its just about understanding what everything is doing. Ok so for now, lets ignore the code part of this, and just focus on the animgraph itself and what is happening.⤶ ⤶ When you open it up you will see this.⤶ ⤶ <upload src="70317/8d993ef829eb84e.png" size="229681" name="sbox-dev_fxR9tFzjzb.png" />⤶ ⤶ Maybe you think this is alot of windows and alot to take in, dont worry, Lets break down each window and understand what is going on in them, here is how we will break them down so its easier for you to follow.⤶ ⤶ <upload src="70317/8d993eff4d89efe.png" size="361468" name="image.png" />⤶ ⤶ Ok, so first things first⤶ ⤶ ## 1 - Preview window⤶ ⤶ The preview window is much like the preview window in the asset browser and other tools in s&box, it gives you a preview of a model, and gives you options to change how it is viewed,⤶ each icon along the top has options.⤶ ⤶ <upload src="70317/8d993f1a675159f.png" size="117401" name="image.png" />⤶ ⤶ . Camera - this just changed how it should be viewed, for example if it should be viewed like a viewmodel.⤶ ⤶ . ground - this just enables or disables the ground below the model⤶ ⤶ . bones - this just allows you to see the bones and joints of the skeleton.⤶ ⤶ . GearCog (edit preview model)⤶ This is where you set the model to be used in the animgraph, clicking it opens this window⤶ ⤶ <upload src="70317/8d993f18d47e015.png" size="7449" name="image.png" />⤶ ⤶ here the + button adds a model input with a search for you to add your model.⤶ the magic wand will automatically add any model that is refencing this animgraph (that is set in modeldoc).⤶ ⤶ once done and closing the window it will now show the top model in the viewport.⤶ GREAT!!!!⤶ now your model is added into the animgraph and we can access its animations!⤶ ## 1 - Preview window⤶ ⤶ The preview window is Contains your model thats being animated within the animgraph. It is most useful when you are testing your final pose within the graph itself via [playback control](https://wiki.facepunch.com/sbox/Animgraph_breakdown~edit#9playbackcontrol) ⤶ <upload src="70317/8db774681caba92.gif" size="7109414" name="sbox-dev_jLOx4S9zxJ.gif" />⤶ ## 2 - Main Inputs ⤶ <note>I am pretty sure this has nothing useful to us, its just some options that you can mess around with in preview mode. ⤶ you will see commonly with nodes that have **TARGET** in its properties a bunch of random stuff and then **Parameter**, all that other random stuff is the Main Inputs, but in sbox from what i can tell its never used, so just use parameters to control your nodes. please correct me if im wrong.</note>⤶ ⤶ <note>This was a common set of base [Parameters](https://wiki.facepunch.com/sbox/Animgraph_breakdown~edit#4parameters) that were common through most animgraphs, although i dont recommend using it, just make and use your own parameters</note>⤶ ## 3 - Motors ⤶ <note>Motors are you input type i guess, it seems the only option you will ever use is player input, or path if you got a model you wanna animate along specified path, but pretty much otherwise it will be left blank</note>⤶ ⤶ Motors are what deal with where the inputs for the graph come from.⤶ ⤶ For example player input motor - says the inputs for this graph is player driven. and will be receiving more direct inputs like forwards, back, left, right from the player.⤶ ⤶ Where the Path motors, says that this model will be moving along a set path instead of multiple directions, basically like an NPC.⤶ ⤶ Motors update twice:⤶ ⤶ - Before the nodes update, so that they can process any input from the game and make it available to the nodes⤶ - After the nodes have finished updating, so that they can perform any necessary fix-up on the root motion calculated during the node update⤶ ## 4 - Parameters Parameters are what you will use to communicate between your gamemode c# code and your animgraph to say what is happening and what animations should be playing. It has your basic + option, to add your parameter type. and a delete option to delete a parameter.⤶ ⤶ <upload src="70317/8d993f2cb638230.png" size="14104" name="image.png" />⤶ ⤶ Here i have set up all the parameter types you can use. lets see what input types they are and what they will do. ⤶ | Parameter | What? | inputs |⤶ | ------------- |:-------------:| -----:|⤶ | Bool | Boolean, its a true or false input, use for on and off state something should be in (like noclip, jump) | true, false |⤶ | Enum | Depending on the number inputted a different state will be outputted, eg 0 - nothing, 1 - pistol, 2 - shotgun, and so on | 0, 1, 2, 3 etc (starts at 0) |⤶ | Float | Precise number input, number with decimal value, very precise!!! | 12.323 and so on, any number, with any decimal place |⤶ | Int | Integer, number value with NO decimal place not percise like float, but more ideal to use these when you can | 12 and so on (NO decimals like .323 only whole numbers!) |⤶ | Quaternion | Oh no, this is a value for rotation, very confusing though, you will input value from other stuff in here, like rotation of hand in vr | x, y, z, w. (imagine like vector with 4 inputs for rotation) |⤶ | Vector | Used for position, pretty much like X Y Z position in world space, basically just 3 Floats. | x, y, z (mainly used for position of something or a position to look at) |⤶ ⤶ Within certain nodes they may ask for parameter input, know you will know what sort of parameter type you got to use. ⤶ bool - on and off. Enum - to choose between multiple animation states. Float - precise vale input. Int - less precise value input. Quaternion - rotation input. Vector - position input.⤶ ⤶ ALSO another thing, when selecting your parameters you will see something pop up in the far right window, properties.⤶ here you can change the default value (if nothing is put in its value will be that deafult), value caps if they have that (highest or lowest input), if bool should reset to default 1 tick after being changed (acting like a button turning off after pressed rather than a switch on and off) other specific options. And all the normal inputs that you get with stuff in the animgraph.⤶ Parameters are what you will use to communicate between your c# code and your Animgraph to tell it what is happening in game (jumping, running forwards, running speed, pose state) ⤶ <upload src="70317/8db774324157e8a.png" size="18914" name="image.png" />⤶ ⤶ Parameters come in 6 different types, bool, enum, float, int, vector and quaternion.⤶ Each one having their own ideal reasons you would use them. ⤶ For example ⤶ - bool - on and off. ⤶ - Enum - to choose between multiple animation states. ⤶ - Float - precise vale input. ⤶ - Int - less precise value input. ⤶ - Quaternion - rotation input. ⤶ - Vector - position input.⤶ ⤶ When you create these parameters you will have setting on them pop up in the [Properties window](https://wiki.facepunch.com/sbox/Animgraph_breakdown~edit#6properties)⤶ ⤶ <upload src="70317/8db77433a82c78f.png" size="10363" name="image.png" />⤶ ⤶ Here you can set base settings, value limits, networking and so on of this specific Parameter. ## 5 - Tags If parameters are used for external code to change stuff, then tags are mainly used for INTERNAL nodes to change stuff. Tags act like the Bool Parameter but they can be triggered by nodes within the animgraph. For example State machines can turn a tag on while its in a certain state to say what is currently happening. These tags can still be seen by the code, but cant be changed via code. ⤶ They can change the output of other nodes based on the tags state.⤶ For example a node can detect if a foot in on the ground, then change a RightFootGrounded tag, this can then make it so a state machine will switch the foot anim from walking type animation to a grounded on. see how that can be useful, since nodes can detect stuff for us rather than making our gamemode do it!⤶ If Parameters are used for external code to communicate values INTO the animgraph, then Tags are mainly used for INTERNAL nodes to communicate OUT of the animgraph. ⤶ Tags can be changed by nodes, and then sent to other systems within the engine, its just a way to communicate an animation event thats happening to everyone else. ⤶ Tags can also affect nodes within the animgraph. <upload src="70317/8d9955e8152c17d.png" size="28942" name="image.png" /> <note>There are also tags that trigger sound, particles, and change stuff set in a model and so on but as far as i know currently i dont think they are used in sbox, or even work? So the only tags i know of currently are the Internal ones</note> ## 6 - Properties ⤶ This window will give you options to change anything in the animgraph. This includes: nodes, parameters, tags, motors and so on.⤶ ⤶ The properties tab allows you to change things such as the name, values, default values and so on, anything important to how it should run or work or display. you will use it a lot.⤶ ⤶ ⤶ ⤶ ⤶ ## 7 - Properties Description / Preview window⤶ ⤶ This area does 2 things, it serves as the window where descriptions will show up, what this means is, if you are ever confused by anything, tag, motor, parameter, node, or even a property inside of anything, you can click it, and it will show a description up there of it (99% of the time, some things have no description it seems) This will help you alot to understand what things do and how to use them so make sure you use it!!! ⤶ BUT also certain nodes, such as animation sequences will push the description window up and then show a small preview window (like the top left one) but for that specific animation.⤶ as can be seen below.⤶ ⤶ The properties window allows you to change specific properties, basically settings within something selected that has properties like... - motors⤶ - parameters⤶ - nodes⤶ - tags⤶ - animations⤶ ⤶ Obviously there are lots and lots of different properties that do completely different things between every different thing you select. but dont worry, *most* properties can be hovered over and they will have a description of what they do! ⤶ Like so! ⤶ <upload src="70317/8db774478b5f5ab.png" size="13165" name="image.png" />⤶ ⤶ ## 7 - Properties Description / Preview window⤶ ⤶ If you dont see this window when you have something selected.⤶ you can view it like so.⤶ ⤶ <upload src="70317/8db77468b9e9be0.gif" size="70366" name="sbox-dev_xAm96BqLCQ.gif" />⤶ ⤶ This little window will give you a description of selected thing, which you can look at if you are ever confused what a node does, it will have a description of what it does!⤶ ⤶ Also with certain nodes this window can become another Preview window for animations and so on, or will display a basic example of what's going on inside Complex nodes (like the state machine node) without having to double click and enter it.⤶ <upload src="70317/8d995464dfd65c0.png" size="216822" name="image.png" /> ## 8 - Node Workspace ⤶ Here is your workspace, most of your focus will be staring at this and the nodes you connect together, you can throw in nodes and change their properties within the properties tab when you click them, so you can say what inputs to go to depending on what the parameters inputted are. or some nodes you can double click if they got a white triangle in the top right to go inside for further editing. (the left, right and up arrows are used to go back into, out of nodes that you can enter)⤶ <upload src="70317/8d9954b97dc65a6.png" size="164256" name="image.png" /> ⤶ it is basically setting up all the decisions and mixing of animations needed for the game to understand what animations to display depending on what parameters are inputted. ⤶ ## 9 - Live preview window? ⤶ This i dont think has an actual name, however it is used to be able to test your animgraph live within the animgraph,⤶ just click the little man, then suddenly the entire animgraph and windows change, they will then allow you to change inputs on the parameters as if you were the code editing them.⤶ also within the node window, it will show you the current path of decisions that are being made in order to get the right animations. ⤶ This is where all your nodes are and connect together, here you will be creating, connecting and messing with all your nodes. here is a basic example of how it works⤶ <upload src="70317/8db7747ca9e1721.mp4" size="4463357" name="2023-06-27 20-49-47.mp4" /> ⤶ Note the workspace will change on nodes with a little white arrow on them. This little white arrow indicates you can go inside the node and do more! ⤶ ⤶ ## 9 - Playback Control⤶ ⤶ The playback control window allows you to preview what your animgraph will output without having to boot up a game and code inputs to the parameters. ⤶ it shows you a live path of your node final pose flow.⤶ ⤶ and allows you to easily set whatever values on your properties to see how they will change the final animation.⤶ ⤶ just click the little man and it will send you into playback mode.⤶ <upload src="70317/8d99547262634bb.png" size="9017" name="image.png" /> ⤶ as you can see its super powerful to quickly test your graph⤶ ⤶ <upload src="70317/8db7745d568e8d3.mp4" size="14103661" name="2023-06-27 20-35-38.mp4" />⤶ ⤶ <upload src="70317/8d99547a1ccebf3.mp4" size="23112013" name="2021-10-22 11-33-25.mp4" />⤶ As you can see, this is really useful to make sure everything is working right, and helps give an idea of what needs to be fixed. ⤶ not it seems there is also the ability to record and save the inputs you place, this is good if you have a recorded sequence of inputs for lets say a path you want an NPC to follow, that way you can easily set it up and record it and use it later on.⤶ ⤶ ## 10 - console ⤶ ⤶ ## 10 - console This is just like a normal console to spit errors out to you if anything goes wrong, but for the most part you dont need to have this open. # this page is WIP and still has stuff that needs to be added, so feel free to make changes or correct any mistakes!