the symptom, in your words

"A hyphen in a sequence name drops the clip from the compiled model, silently"

✓ verified on 26.08.05
lane Rigging & animationposted

▸ SYMPTOM

You author a clip, add it to a model's animation list, and compile. The fbx bakes, the vmdl compiles green with zero errors and zero warnings, and the sequence is simply not in the model at runtime. Assigning it plays nothing and leaves the body in its default pose.

The one difference between a clip that works and this one is a hyphen in its name.

▸ CAUSE

The model compiler drops any AnimFile whose name contains a hyphen, and nothing anywhere reports it.

One test isolates the cause. Bake one clip twice from the same source fbx, changing only the name. The hyphen-free name phone_look_probe plays for 0.63 s. The name phone-look, built from the identical fbx, reports a duration of 0.00 s. Rename that same entry in the animation list to a hyphen-free word while leaving source_filename = phone-look.fbx untouched, and the clip comes straight back to life. The name is the cause, not the source path. Underscores and digits are fine.

The name is usually also a filename, and filesystem-safe is a weaker rule than compiler-safe. A pipeline that accepts a hyphen because the file writes fine still hands the compiler a name it will discard.

A second trap hides the first. The SkinnedModelRenderer.Sequence.Name setter accepts and echoes back a name the model does not have. Assign definitely_not_a_sequence and it reads back as definitely_not_a_sequence, reports a Sequence.Duration of 0.00, and leaves a motionless body in the default pose. That reads to a user as broken playback rather than a missing clip, so the obvious guard against a bad name cannot fail.

▸ FIX

Sanitise the name once, at the point where the typed name becomes a stored one.

  1. Strip the hyphen where a person's typed name first becomes a stored name. That is the single point the file, the fbx, and the sequence all derive from. Sanitise there with the strictest rule, so the file, the fbx, and the sequence stay one word.
  2. Apply the compiler rule, not the filesystem rule. The name doubles as a filename, so people reach for filesystem-safe. Compiler-safe is stricter: remove hyphens, keep underscores and digits.
  3. Check membership before you assign the sequence. Test the name against Sequence.SequenceNames, the model's own list, before writing Sequence.Name. The setter will not tell you the name is absent.
  4. Print the list on a miss. When the name is not on SequenceNames, log the names the model does have. The failure is otherwise indistinguishable from a rig, a clip, or a playback fault.

▸ WHY IT WORKS

The clip is lost at compile, so the only durable fix runs before compile: keep the stored name hyphen-free at its single source. The runtime check covers the rest. Because the setter reports success on a name the model lacks, membership in SequenceNames is the only signal that the clip is really there, and printing the real names turns a dead end into the next thing to try.

Verified on engine 26.08.05: seen in a real project.
s&box moves fast; an undated fix is a liability. Spot a stale detail?
changelog
  • Published

Want to know when new guides or fixes drop? Join the community to help build this out. Report gotchas, flag outdated fixes, or just lurk.

Join the Discord