Skip to content

Game.Prefabs.CharacterStyle

Assembly: Assembly-CSharp
Namespace: Game.Prefabs

Type: class

Base: PrefabBase

Summary:
CharacterStyle defines per-character animation metadata and root-motion calculation data used by character prefabs. It contains shape and bone counts, a gender mask, and a list of AnimationInfo entries describing available animation clips, playback, target render prefab, activity/state masks and precomputed root-motion information. The class provides helper functions to retrieve animation assets, enumerate asset dependencies, declare ECS components required for the prefab, and to calculate and populate root-motion (start/end offsets and rotations) for animations based on the bone hierarchy and rest pose.

Fields

  • public int m_ShapeCount
    Number of shapes (blendshapes / variations) supported by the character. Used when decoding per-shape animation elements and when computing per-shape root motion.

  • public int m_BoneCount
    Number of bones considered in the animations for this character style.

  • public GenderMask m_Gender = GenderMask.Any
    Mask indicating which genders this character style applies to (e.g., Any, Male, Female).

  • public AnimationInfo[] m_Animations
    Array of AnimationInfo entries describing each animation available for this style. Each AnimationInfo contains references to the animation asset, target RenderPrefab, animation type/layer, frame information, activity/state masks, playback settings, and a place to store computed rootMotion data.

Nested types (summary of important nested classes)

  • public class AnimationMotion
  • public float3 startOffset — start positional offset of the root motion for a given shape.
  • public float3 endOffset — end positional offset of the root motion for a given shape.
  • public quaternion startRotation — start rotation (quaternion) for the root bone for this shape.

  • public quaternion endRotation — end rotation (quaternion) for the root bone for this shape.
    Represents per-shape root motion offsets and rotations.

  • public class AnimationInfo

  • public string name — animation name.
  • public AssetReference<AnimationAsset> animationAsset — reference to the animation asset.
  • public RenderPrefab target — render prefab target for this animation (may be null).
  • public Colossal.Animations.AnimationType type — animation type (from engine enum).
  • public Colossal.Animations.AnimationLayer layer — animation layer (e.g., BodyLayer).
  • public int frameCount — number of frames in the animation.
  • public int frameRate — frame rate for the animation.
  • public int rootMotionBone — bone index used as the root-motion reference (computed/populated by CalculateRootMotion).
  • public AnimationMotion[] rootMotion — per-shape root-motion data computed for this animation.
  • public ActivityType activity — activity associated with this animation.
  • public AnimationType state — animation state enum.
  • [BitMask] public ActivityCondition conditions — bitmask of conditions that must be met for this animation.
  • public AnimationPlayback playback — playback settings for the animation.
    Describes a single animation's metadata and where computed root-motion data is stored.

Properties

  • public override bool ignoreUnlockDependencies => true
    Indicates that this prefab ignores unlock dependencies (override from PrefabBase). For CharacterStyle this property always returns true.

Constructors

  • public CharacterStyle()
    No explicit constructor is defined in the source; the default constructor is used. Initialization of fields like m_Gender is performed inline (m_Gender set to GenderMask.Any).

Methods

  • public AnimationAsset GetAnimation(int index)
    Returns the AnimationAsset referenced by m_Animations[index].animationAsset using the global AssetDatabase. Throws or fails if the index is out of range or the asset reference is invalid. Use to obtain the runtime AnimationAsset for a given animation entry.

  • public override void GetDependencies(List<PrefabBase> prefabs)
    Adds dependent prefabs for this CharacterStyle to the provided list. Implementation adds any non-null RenderPrefab target referenced by each AnimationInfo (animationInfo.target) to the prefabs list in addition to base dependencies. Useful for ensuring render prefabs are included when resolving asset dependencies.

  • public override void GetPrefabComponents(HashSet<ComponentType> components)
    Adds the set of ECS ComponentType entries required by this prefab to the provided set. This implementation adds:

  • CharacterStyleData (read/write)
  • AnimationClip (read/write)
  • Game.Prefabs.AnimationMotion (read/write)

  • RestPoseElement (read/write) These components describe the data the prefab requires on entities.

  • public void CalculateRootMotion(BoneHierarchy hierarchy, Animation animation, Animation restPose, int infoIndex)
    Calculates per-shape root-motion offsets and rotations for the animation at m_Animations[infoIndex] and populates that AnimationInfo's rootMotionBone and rootMotion array. Behavior and notes:

  • Determines number of shapes considered (uses m_ShapeCount unless animation has only a single shape element).
  • Selects a root-motion bone index (num2) — if the animation layer is BodyLayer, it looks for bone index == 1 in animation.boneIndices and uses that as the root; otherwise defaults to 0.
  • Builds lookup arrays mapping bone indices to animation element indices and shape indices to element indices.
  • For each shape, it decodes the start element (frame 0) and end element (last frame) for the chosen root bone and then walks up the bone hierarchy to accumulate parent transforms (position and rotation), applying parents' start/end transforms to compute the final world-space start/end offsets and rotations for the root bone.
  • If the animation does not contain the expected bone element, the corresponding element is taken from the restPose.
  • Populates m_Animations[infoIndex].rootMotionBone with the chosen root bone index and m_Animations[infoIndex].rootMotion with an array of AnimationMotion (one per shape) containing startOffset, endOffset, startRotation, endRotation.
  • This computed data is useful for aligning entities to animation-driven motion and for blending/movement logic that depends on root motion.

Usage Example

// Example: retrieve an AnimationAsset and compute root motion for the first animation entry.
// Assume `characterStyle` is an instance of CharacterStyle already loaded, and
// `hierarchy`, `animation`, and `restPose` are obtained appropriately.

AnimationAsset animAsset = characterStyle.GetAnimation(0);
// animAsset gives access to animation data; you would also get `Animation` and `RestPose`
// decoded representations required by CalculateRootMotion:

// pseudo-code placeholders for obtaining decoded Animation / BoneHierarchy objects:
Animation animation = animAsset.DecodeAnimation(); // example; actual API may differ
Animation restPose = animation.GetRestPose();     // example; actual API may differ
BoneHierarchy hierarchy = characterStyle.GetBoneHierarchy(); // example helper

// compute root motion and store it into characterStyle.m_Animations[0].rootMotion
characterStyle.CalculateRootMotion(hierarchy, animation, restPose, 0);

Notes and implementation tips: - CalculateRootMotion expects animation decoding APIs (Animation.DecodeElement, element raw layout) and BoneHierarchy hierarchy consistent with game asset formats. When writing mod code, ensure you supply compatible Animation and rest-pose instances. - m_Animations[].rootMotion and rootMotionBone are populated by CalculateRootMotion; calling it during asset import/initialization is typical. - GetPrefabComponents must be called by prefab registration logic to register required ECS component types for the prefab.