vlazed Tutorial

This article is stored here for archival purposes only. Some information may be outdated.

Stop Motion Helper: Unofficial

This is the second part of the tutorial, which goes over the new features added for the unofficial Stop Motion Helper (SMH) 4.0. To summarize, these new features are the following:

• Animatable bonemerged entities (from the regular Bonemerger to the Composite Bonemerger to the Advanced Bonemerger),
• Audio playback to enable sound synchronization cues
• Motion paths to trace out the trajectory of a bone's path over time
• Additional modifiers for the entity editors and volume clouds
• New concommands to improve navigation over the timeline

Aside from that, it is uncertain if the official version will implement these features the same way as this fork implements them (particularly selecting bonemerged entities or audio playback). If the official version releases these features, please refer to their tutorials.

Console Variable and Command Summary

Command Name	Arguments	Description
smh_previous	n	Move the playback back by n frames. If past 0, move the playhead to the end of the timeline
smh_next	n	Move the playhead forward by n frames. If past the frame count, move the playhead to the beginning of the timeline
smh_previousframe	none	Jump to the previous keyframe before the playhead
smh_nextframe	none	Jump to the next keyframe after the playhead
smh_zoom	d	Set how many keyframes can be seen on the timeline. If the frame count is n and smh_zoom is set to n, then we will see exactly n frames on the timeline
smh_fps	n	Set the playback rate of the timeline to n frames per second
smh_framecount	n	Set the length of the timeline to n frames
smh_smooth	n	Smooth the frame on the playhead, or multiple selected frames, n times
smh_smoothall	n	Smooth all frames n times
smh_motionpathbone	string	Select the bone to view its trajectory
smh_motionpathrange	n	Restrict how many nodes on the motion path to view
smh_motionpathsize	d	Change the size of the nodes on the motion path.
smh_motionpathoffset	f f f	Offset the position of the nodes with respect to the bone.
smh_autosavetime	d	Set how long, in minutes, it should take for the game to automatically save an animation. Set to 0 to disable
smh_majortickinterval	n	Set the interval which to distinguish frames by size. Set to 3 to disable
smh_ghostxray	d	Set to 1 to enable XRay ghosts (ghosts are colored solid, bright, and ignores obstructions)
smh_unpack	none	Reverse the 'Pack' command by manually removing SMH data from a GMod save or a dupe
smh_stretch	f	Stretch (or compress) keyframes across timelines. This can replace existing keyframes
smh_audioclip_scale	n	Set the thickness of the audioclips outside of Edit Audio Track mode
smh_cycleselected	0 or 1	Cycle through all bonemerged (child) entities of the selected entity, when right-clicked mode
smh_lockselected	0 or 1	Prevent the selection of other entities

User Interface

The UI in this version of SMH reflects the same version dated at this time, or similarly, to the workshop version around February 2, 2022. The only new additions are the following:

1. Keyframe Settings,
2. Audio playback, and
3. Motion Paths.

Although the keyframe settings float above the timeline, it is not moveable. Also note that one can access the motion path settings by navigating to the Settings button and clicking the button that says "Motion Paths" (between "Ghost transparency" and "Physics Recorder"). The audio playback user interface are new features added by the SMG4 team, from Version 0.1.0.

From the screenshot, we will introduce the new features, naturally stepping through the user interface from the left ot the right.

Features

Keyframe Manipulation and Navigation

This fork of SMH extends user's abilities to move through the timeline, adjust keyframe positions, and influence the effect of the animation. These can be done through the console, or through the readily available user interface.

The first set of option surrounds the "Select All" button. As expected, this option will select all keyframes in the timeline. This circumvents the need to 1) select the first keyframe, 2) zoom or scroll to the right to find the ending keyframe, 3) select the final keyframe, and compresses the steps to do this into one (this saves two keystrokes). We can then manipulate these keyframes in any way, either by offsetting them to a different point on the timeline, deleting them all, or performing the smoothing operation. Similarly, the options next to "Select All", "Select Left" and "Select Right", perform a similar task to "Select All": the "Select Left" (or Right) button will select the keyframes to the left (or right) of the playhead, including the keyframe on the playhead.

In addition, the select buttons acts as an invert operator. To explain, press "Select All" twice, and the keyframes will be deselected. The following video will illustrate another use case, which involves selecting a subsequence of keyframes in the timeline and the other keyframes.

Smh.Selectall.Demo.mp4

We mentioned earlier that we can smooth keyframes. This keyframe manipulation goes by different names, two of which I know: the arc method, and the Eltorro trick (see this video for more information). We can perform this keyframe manipulation in two ways: the user interface, or with the concommand smh_smooth n, where n is a whole number indicating how much should be smoothed. This is known as the arc method because the output after performing the smoothing command is an arc, as seen in the following video. Notice the green motion paths in the smoothing trick has transformed from two straight lines into an arc. Also note the chat message indicating that smoothing has completed.

Smh.Smoothing.Demo.mp4

In the video, we use the "Smoothness" slider to vary how much of an arc that we want. Smoothing adds an additional frame to the animation. If one starts off with one frame, smoothing will add an additional frame for a total of two frames: in general, if one begins with n frames, they end up with n + 1 frames after a smoothing operation.

Smoothing can also be done with multiple selected frames, as seen in the next video.

Smh.Smoothing.Demo.2.mp4

Next to smoothing, the animator can use the Stretch (or Compress) button to increase or decrease the length of time of an animation. This relies on selected keyframes to stretch or compress, making the selection buttons a natural application for this feature. The next video will showcase this feature in action.

smh_stretching.mp4

Beware that stretch and compress can replace keyframes on the timeline: stretching may replace unselected keyframes, while compressing may replace selected keyframes.

The video also demonstrates some new navigation features in SMH. Like any console command, they can be binded them to a key or input button. They are summarized in the following table. Note that n is a whole number.

Command Name	Arguments	Description
smh_previous	n	Move the playhead back by n frames. If past 0, move the playhead to the end of the timeline.
smh_next	n	Move the playhead forward by n frames. If past the frame count, move the playhead to the beginning of the timeline.
smh_previousframe	none	Jump to the previous keyframe before the playhead.
smh_nextframe	none	Jump to the next keyframe after the playhead.
smh_zoom	n	Set how many keyframes can be seen on the timeline. If the frame count is n and smh_zoom is set to n, then we will see exactly n frames on the timeline.

Audio Playback

The next set of UI enables audio playback. The four buttons on the timeline tab each open a window, where one can 1) explore the sound directory, 2) load an audio sequence, 3) save an audio sequence, and 4) manipulate the audio. In 4), grayed out buttons indicate that they will be implemented in the future. Also notice that audio sequences will also save the framerate and frame count, preserving them as they were at some point in the past.

To add your own audio to use, you must do the following:

• Add them into the garrysmod/sound directory or in an addon folder in garrysmod/addons/your-sounds/sound/ (addon folder name can be whatever).
• Ensure they are in .mp3, .wav, or .ogg (I recommend .mp3 to save on file size).
• Ensure they do not contain unicode characters.
• Ensure they are in the following sample rates (reference. See also WAV and MP3)
  • 11025 hz
  • 22050 hz
  • 44100 hz

If we insert an audio clip into the timeline in 1), and check "Edit Audio Track", we will be able to see the clip on the timeline. This clip gives us the length of the clip, and its waveform, indicating where in the clip is it the loudest. The length of the clip on the timeline is influenced by the framerate and how much the timeline has zoomed in or out (after importing engineer_taunts12.mp3, I executed smh_zoom 500).

We can play the audio clip through +smh_playback, given that we disable smooth playback to ensure consistent audio playback. In addition, we can also "scrub" the audio clip by dragging the playhead over a section of the clip, and it will play a part of it. The following video showcases both the audio scrubbing and audio playback feature.

smh_audioscrubbing.mp4

We can then use 4) the Audio Clip Tools to manipulate this audio clip. To delete an audio clip, the playhead must be adjusted to the beginning of the audio clip (not somewhere in the middle, or at the end). We click on it twice to delete the audio clip (the first click will confirm if one is sure to delete the audio clip). Alternatively, if we wanted to delete all audio clips, we use "Delete All."

Audio sequence placements on the timeline are saved in the garrysmod/data/smh/audio folder. It is recommended to keep these audio placements in this directory and animation files elsewhere.

Selecting Bonemerged Entities

By default, Stop Motion Helper is capable of animating any entity, but it is not capable of selecting bonemerged entities. This fork adds two methods of selecting bonemerged entities, enabling one to animate a bonemerged prop. The following video illustrates two ways to select a bonemerged entity:

1. Right-click on the entity multiple times to cycle through an entity's bonemerged items, or
2. Select the bonemerged item through the properties menu.

Smh.Bonemerge.Demo.mp4

Once you have selected the bonemerged entity, you can start animating the bonemerged entity through a tool such as the Ragdoll Mover (RGM).

There are a few behavior quirks to be aware of when animating bonemerged entities with either the Advanced Bonemerge Tool (ABT) or the Composite Bonemerge Tool (CBT). The following bulletpoints list some gotchas when working with these entities, assuming the user also uses Ragdoll Mover (RGM).

• CBT uses the same bone manipulation features (inflating bone scale, moving the bones with Edit Bones, using RGM) as Stop Motion Helper. If you are parenting an entity onto a bone using CBT, SMH will override your settings. It is recommended that you use ABT to parent the entity instead, as it stores its own offsets.
• With ABT, Ragdoll Mover does not update its gizmo position when going between keyframes on SMH. You will need to reselect the bone (press R twice) to update the gizmo position.

You can disable the selection of bonemerged entities with smh_cycleselected 0. smh_lockselected 0 will disable entity selection altogether.

Visualizing Bone Motion Paths

The last addition to the SMH UI is a window for modifying motion paths. In the earlier media on this tutorial, motion paths are shown as green circles, with green lines connecting between them. These green circles are keyframes, while the green lines show the path that the animated object will take. Yellow circles indicate the keyframe that the playhead is in. Red lines are shown before the yellow circles to indicate the past. Immediately before the previous frame and next frame, a number also shows up on the path, indicating keyframe distance.

We can adjust how much of the trajectory we want to see with the "Path Range" slider. For reference, setting the slider to 1 will show two green circles immediately before and after the keyframe (as in Ghost Previous/Next frame); setting the slider to 2 will show four green circles, and 3 shows 6; in general, setting the slider to n will give us 2n circles.

Finally, we can choose which bone to follow in the "Bone Name" text entry. Simply reference the bone that you want to follow (for instance, one can use Ragdoll Mover to identify), and type its name (it is case-sensitive!). Based on this, we can use the Offset sliders to visualize rotations.

Alternatively, these settings can be changed in the console. The following table summarizes these console commands. Note that n is a whole number, d is a decimal-point number, and string can be a name.

Command Name	Arguments	Description
smh_motionpathbone	string	Select the bone to view its trajectory
smh_motionpathrange	n	Restrict how many nodes on the motion path to view
smh_motionpathsize	d	Change the size of the nodes on the motion path.
smh_motionpathoffset	d d d	Offset the position of the nodes with respect to the bone.

Packing

Packing allows entities to retain their animations into an SMH Package, which persists when duplicating or reloading a save. It can significantly reduce the time to "reload an animation session", especially when the animation involves multiple entities.

SMH packages in this unofficial version of Stop Motion Helper differs significantly from the official version. In short, there is a process to ensuring that animations are packed properly; the tradeoff is the reduced likelihood of crashing when loading an animation package in a GMod save or from a duped entity (or set of entities).

Earlier versions of the SMH Package included all the keyframe data per entity. In this version, the SMH Package now points to an SMH save file, and the custom name (from the Properties menu) which the entity took on for the save file.

To ensure SMH animations are saved in a GMod save:

1. In the save menu, ensure that you have an existing save file, and the name of the save is the same as the existing save file.
2. Click the "Pack" button. SMH will inform you in the chatbox if the packing was successful.

To ensure SMH animations are saved in a GMod save, you must copy an entity with animations with the Duplicator. Copying an entity with animations add a duplicator tag to the SMH Package, allowing Stop Motion Helper to distinguish dupes from saves, and to apply duplicator offsets correctly. When you click the "Pack" button, SMH will also mention in the chatbox that the save has dupes, indicating that the duplicate is armed with an entity with animations, which you can place in any position that you choose.

If you are completely done with duplicating entities and plan to make a GMod save, make sure to click the "Pack" button again, to clear the duplicator tag from the SMH Package. Failure to do so will make Stop Motion Helper apply duplicate offsets to all entities in the GMod save. Note that while the animation will look odd, the save file exists, allowing you to fix these changes (with minor inconvenience).

Miscellaneous

There are more features in this version that value an explanation. However, we have decided to omit this explanation by listing them down for you to explore. In addition to the aforementioned features,

• This fork adds more entities to animate: SMH can now animate GMod's default sun, sky, and fog editors. In addition, the fork also adds a modifier for volumetric clouds, allowing its parameters to be adjusted.
• This exit save feature allows the game to save your SMH animation when the server shuts down with players connected. Similarly, if a player leaves or reloads a map, they will automatically save their progress. Exit saves are found in the garrysmod/data/smh folder, named as exit_save_NICKNAME_ID, where NICKNAME is your Steam name (not username), and ID is your account id.
• Similar to the exit save feature, the fork also adds a single-player-only auto saving feature, through the concommand smh_autosavetime d, where d is decimal number. Auto saves are located in garrysmod/data/smh folder, labeled as auto_save_NAME_00#, where NAME is your Steam nickname, and # is a number between 1 and 5. Up to 5 autosaves are allowed; otherwise, they get deleted afterwards.
• The timeline can be customized further with smh_majortickinterval n, where n is a whole number between 3 and 16. This command is also found in Settings as a slider. The command distinguishes parts of the timeline at intervals to make keyframe placement easier, as well as for visual aesthetic. Set it to 3 to disable.
• Framerate, frame count, and timeline length are now console variables, in the form of smh_fps, smh_framecount, and smh_zoom, respectively. This allows you to save your timeline settings. The first two require whole number inputs, while zoom requires a decimal number (although it is saved as a whole number).
• The physics recorder now includes two more indicators to show that one is recording: a beeping sound akin to SFM during the countdown to record, and a red circle on the top right, which fades when nearing the end of the physics recording session.
• +smh_playback command has been extended to play the SMH animation at any frame other than at the playhead. To see this, provide a whole number argument to the command (e.g. +smh_playback 0 to play an animation from the beginning).
• Ghosts can be set into 'x-ray mode', which changes a ghost's appearance to a solid color and makes them ignore obstructions (they can be seen through walls or objects). You can use this if you are unable to see the previous/next frame ghost (due to $alphatest/$translucent materials).

Other Resources

The features above were built to introduce workflows involving audio and animation synchronization, bonemerged entity animations, and arc-ed movements. The links take you to additional resources to help improve your animation process.

• Precise Aim Vector: This script increases the precision of your mouse cursor as seen by the server, which fixes jittering when you use the Ragdoll Mover gizmos with an unlocked cursor (via holding C or through other means).
• Sync SMH with RGM: This script interfaces Ragdoll Mover with my fork of Stop Motion Helper to automatically rename the smh_motionpathbone when one selects a bone with Ragdoll Mover. It also updates the Ragdoll Mover gizmo to properly position and orient itself to a nonphysical bone, and it sets entity constraints automatically.
• Catmull-Rom Camera SMH Interface: This is a modification of the original addon to allow one to bake a camera's spline path into a camera entity (standard or Advanced Camera).
• Freeze Props on Spawn: This script freezes props when they spawn. This also freezes props when you load a save. This is useful if, for some reason, your save does not keep props frozen (such as with effect prop assemblies). This is an alternative to using phys_timescale 0.
• Sync SMH to Poser Tools: This script allows SMH to set the faceposer sliders, move the eyeposer target, and move the fingerposer draggers when keyframed, which prevents the user from needing to reselect an entity to update the UI.
• PenAkTools: A collection of quality-of-life scripts for animation by PenolAkushari. The ones I use most often are the Macro Replacer (my version with presets), the Fake Depth post-processing effect, and the Ragdoll Weight tool.