Packing

Video Tutorial

Text Tutorial

Intro

Packing is a new feature for SMH that stores animations into all entities in a scene. The goals of SMH's packing system are

1. To integrate into the GMod save system. That is, loading into a GMod save will also load all stored animations of an entity
2. To integrate with the duplicator system. This allows one to clone an entity animation and put it in different places.

Point 1 is important; in old versions of SMH, the animator manually loads animations into entities by selecting each entity and loading its correct animation. This becomes cumbersome as you work with more entities. Point 1 automates the loading process, allowing you to immediately focus on animation.

Point 2 poses as an alternative to the existing spawner system. A bonus feature, however, is that the packing feature allows you to store an animation inside of a dupe and share it with other players on the Steam Workshop.

Packing is a powerful feature that can save you and others time and headache in an animation project. If you want to make the most out of animating with SMH, you should know these two points. Let's go over how we can do that.

Packing technicals

We define a packing as an operation that stores information about an animation into an entity.

Packing stores animation information for each entity with keyframes in the scene.

There are two things that can happen during packing, and it depends on the console variable, smh_packentity

smh_packentity 0

The following packing data is stored for each entity with keyframes:

• The path to the animation file, relative to garrysmod/data/smh
• The entity name as defined from the Properties menu
• A dupe tag

The path to the animation file is important. If you are loading into a packed GMod save, SMH looks for the animation file, and then loads the correct animation using the stored entity name.

The dupe tag is an indicator that allows one to properly clone an entity's animation into different places.

We recommend using this if you want to save and load a scene animation into a GMod save file, or if you want to duplicate animated entities while avoiding the limitations of smh_packentity 1

smh_packentity 1

Keyframes are stored directly for each entity, rather than an animation file path, name, and a tag.

Packing an animation into an entity results in large GMod save / dupe files. Hence, we recommend this if you want to duplicate simple animations in an entity around, or if you want to share an animation in the Steam Workshop.

Note

The smh_packentity variable saves when you leave / reload a map. If you want to guarantee certain packing behavior, make sure smh_packentity is set to the value that you want.

Important

Know the differences of smh_packentity 0 and smh_packentity 1. We will make use of that behavior for the next sections.

Saving and Loading

Important

Before saving and loading an animation into a save file, set smh_packentity 0. This enforces the packing system to store animations from an animation file into the scene. This prevents weird behaviors.

Important

You should be familiar with saving and loading first before we get into packing. See the saving and loading sections of the tutorial, or watch this part of the video tutorial

The packing feature allows you to save the animation scene into a GMod save file (.gms) and reload back into the GMod save to pick up where you left off.

To pack an animation file into a GMod save, you follow these steps:

1. Open the SMH save menu,
2. Select an animation file in the current directory, and
3. Click the "Pack" button.

The chat box will notify a success or failure of the packing operation. If you get a failure, verify that the animation file exists in the directory before packing.

Note

When packing, sometimes the chat will notify you about a "save path tagged for dupes! Click Pack again to remove the dupe tag." Since we are packing animations into a GMod save and not duplicating any entities, we click "Pack" again. You can click it more than two times to ensure you remove any dupe tags. The next section will go over the dupe tag indicator.

After verifying a success of the packing operation, we can create a GMod save file by going into the spawnmenu and hitting the Save button, or by running gm_save in the console. This creates a packed GMod save: a save with per-entity animation data stored into it.

To verify that this works, load into the new save file, and select any of your entities to check if the keyframes still persist.

Gotchas

• If you are recording keyframes for an existing entity and have made a packed GMod save, you do not need to create another packed GMod save every time that you update the animation file. When you reload back into your packed save, SMH will automatically load your updated animations back into all animated entities in your scene.
  • You must update the animation file to see new changes show up with your animation when you reload into the game. The "Pack" feature does not automatically record new changes.
• If you record keyframes for a new entity into SMH and update the same animation file, you must run the packing steps again and create another GMod save. The new entity needs to be packed so that SMH can automatically load its animations when loading into a GMod save.
• If you want to share a packed GMod save, you need to send both the GMod save, the animation file, and the directory which includes your animation.
  • For example, if the sender sharing an animation is stored in projects/project_1/project_1_01_001_final.txt, the receiver needs to ensure that they have the projects/project_1 directory in the smh folder; the receiver must store the animation file (project_1_01_001_final.txt) in that desired directory
  • As a reminder, animation files are saved in garrysmod/data/smh

Duplicating entities

Duplicating can happen in two ways, and it depends on the console variable smh_packentity

smh_packentity 0

You follow the same packing steps in the Saving and Loading with the Packing Feature section. However, you keep the dupe tag rather than discard it (click the "Pack" button once).

Note

If you lose the dupe tag, you can pull out the duplicator and right-click on entity to re-apply it back. From there, just hit the "Pack" button again.

Afterwards, copy the entity with the duplicator and paste it in another location. This effectively offsets the entity's animation, just like the Spawner system.

smh_packentity 1

Before packing, you need to have smh_streamdupes 1 (this is enabled by default).

Clicking the pack button will store keyframe data directly into the scene. You do not need to worry about the dupe tag not showing up. You can then duplicate the entity and its animation.

Gotchas

• With smh_packentity 1,
  • Keyframe data is stored, not a path to the animation file. That means that if you modify the keyframe data and click pack again, the changes will immediately show up in your duplicate.
  • GMod dupes have a 2 MB limit. Keyframe data makes up a majority of the storage. Take this into consideration.

Saving and Loading with smh_packentity 1

Caution

This section describes the old packing behavior which imposes a limitation with saving and loading big animations. We include it here for documentation purposes.

After subscribing this addon, you may have noticed a change in gm_save behavior: you need to unpause the game to make GMod saves. This side effect stems from how smh_streamsaves 1 works, and it allows one to make GMod saves past 256 KB (an internal networking limit).

We can make use of this behavior and smh_packentity 1 (the ability to store keyframe data directly into entities) to pack animations directly into a GMod save. Loading into the GMod save will load the keyframe data.

With smh_packentity 1, the gotchas from the previous section do not apply here; you do not need an animation file. Instead, you use the "Pack" button and gm_save (or the save button in the spawnmenu) to save your animations directly in a GMod save.

An important tradeoff to consider is the file size limit. The GMod save system internally uses the duplicator system, so for safety, we impose a limit of ~2 MB worth of animation data for a GMod save. This makes smh_packentity 1 impractical for GMod saving and loading.

Tip

The chat notifier for the pack button differs with smh_packentity. If you plan to make a packed GMod save with smh_packentity, ensure that the message indicates packing into "the following save path:"

Unpacking

After hitting the pack button, or when loading into a packed GMod save, an entity's keyframe data will persist. When loading into a packed GMod save, SMH will automatically load any animations for each entity in the scene.

To prevent this from happening, you can run smh_unpack. This cleans up any packing data in your scene, allowing you to save a scene without animations.

Alternatively, you can also run smh_disablepacking 1. This prevents SMH from loading animations automatically, but preserves the packed data in the scene.

Note

smh_disablepacking saves you leave / reload a map. If you find that SMH is not automatically loading animations into your scene, make sure to set smh_disablepacking 0, and then reload the GMod save.