Questlight Studio
Docs / Character visuals and animation

18. Character visuals and animation

In short: a character's looks are data. A look (appearance) names a body, optional modular parts, a thin Anim Blueprint and an animation set, and the battle systems play animations and effects from that data. You can bring characters in with one click from a single mesh, import a whole pack, sort thousands of clips with the Animation & FX Library, add paired finishers, and render portraits and icons, all without writing an Anim Blueprint.

18.1 Basics

18.1.1 The pieces

PieceWhat it is
Look (URSECharacterAppearance)The data asset a character points to in its Appearance field: the parts, material variants, the Anim Blueprint, the animation set, the capsule and the attachment points.
Body presetA project-wide body (mesh, Anim Blueprint, animation set, feet offset, capsule, anchors) stored in Project Settings → RPG Saga Engine → Character Visuals → Body Presets. A look can name one instead of carrying its own.
Animation set (URSECharacterAnimSet)One slot per moment: ready, casting, guard, hits from each side, knock-outs, get-up, victory, dodge, turns, portrait pose, talk, expressions, and the real-time action slots (combos, dodge, parry, block).
Anim BlueprintA thin child of URSECharacterAnimInstance. All battle logic is in C++, so the graph is only locomotion, a slot and an output. You never need to edit one.
AnchorsNamed points on the body (Appearance.Anchor.HandRight, HandLeft, WeaponTip, Muzzle, Chest, Head, Feet, Ground) where effects and projectiles attach. The same ability presentation then works on every body.

If a character has no look, the project falls back to Character Visuals → Fallback Appearance (capsule-and-cube placeholders tinted by team), so a battle is always playable.

18.1.2 Fastest way in: New Character from Mesh

  1. Import your rigged humanoid model (FBX or glTF) into the project. It must be a Skeletal Mesh.
  2. Right-click the mesh → RPG Saga Engine → New Character from Mesh.... (Or RPG Saga Engine → Advanced tools → New Character from Mesh..., or the Studio's New character wizard.)
  3. Check the Display Name (made from the file name), pick a Class and the Kind: Party Member (every battle mode), Recruitable (Tactics units) or Enemy.
  4. Leave Animations on Auto, and optionally set Target Height in cm.
  5. Press Preview to read what will happen, then Create Character.

You get, in a folder named after the character under /Game/CharacterPacks: an Anim Blueprint, an animation set, a body preset, a look, ready attack presentations, and, with a class, the character data. Running it again on the same mesh updates the same assets. Models without animations borrow the UE mannequin's, retargeted: install them once with RPG Saga Engine → Advanced tools → Install UE Mannequin Kit.

18.1.3 A whole pack: the character pack importer

For a pack of many characters or skins that share animations:

  1. Import the pack and leave it where it is. The importer never edits it.
  2. RPG Saga Engine → Advanced tools → Import Character Pack... (or right-click the folder → RPG Saga → Import Character Pack...).
  3. Choose the Source Folder, a Profile and the Target Folder.
  4. Press Dry Run and read the report: skins, triangles per LOD, grounding, animations per slot, anchors, weapons, effects.
  5. Press Apply. Run it again after changing the profile: names are deterministic, nothing is duplicated.

Per character it creates ABP_<Character>, DA_AnimSet_<Character>, montages with an RSEImpact notify on the hit frame, ready ability presentations, and optional character data (DA_Char_<Character>). Per skin it creates DA_Look_<Character>_<Skin> and color variants.

18.1.4 Sorting clips and effects: the Animation & FX Library

Bought three animation packs and a magic effects pack? RPG Saga Engine → Advanced tools → Animation & FX Library... reads every clip and effect, decides what each one is, lets you fix the few it got wrong, builds styles ("Sword & Shield", "Staff", "Bow") and dresses your abilities.

  1. Scan Folder for each pack (select the folder in the Content Browser and press From Content Browser first).
  2. Tick Needs review only and correct the orange-confidence rows with the bar under the grid (Set, Accept, Ignore, Back to Automatic). A rescan never changes your Manual rows.
  3. Type a style name, pick a weapon, press Auto-build Style.
  4. Select characters or classes in the Content Browser, press Assign to Selected, then Apply Styles.
  5. Press Dress My Abilities.

18.2 How it works

18.2.1 How a look becomes a character

URSEAppearanceComponent builds the look on an actor: the leader skeletal mesh with the Anim Blueprint, follower parts that copy the leader's pose (leader pose component, so they are cheap), rigid parts on sockets, material variants, and the visible pieces of the worn equipment. Assets load asynchronously in game. There is no tick: everything happens on events. If the owner has no look, it keeps its placeholder shapes.

Parts are FRSEAppearancePartSpec entries with a slot tag (Appearance.Slot.*), a skeletal or static mesh, an attach socket, materials, and, for weapons, a weapon presentation and hold type (see Weapons). Equipment parts replace the part with the same slot. A look is modular (ERSEModularBody: Auto, Modular, SingleMesh) when it has several skeletal parts; a single-mesh body only shows rigid equipment (weapons, shields, hats) and pieces for slots it already has, so armor never clips through it.

Variants are named material changes per slot (a palette, an outfit color). The character data picks one by name.

18.2.2 The animation flow

Battle code never plays an animation by name. It sets a battle state (ready, charging, casting, guard, down, victory) and fires reactions (hit from a direction, knock-out, dodge, blocked), and the Anim Instance picks the clip from the animation set slot. Several clips in a slot play at random (seeded, so a battle replays the same). Impact timing comes from the RSEImpact anim notify on the hit frame, or is estimated. Knock-outs are played and held on their last pose.

Locomotion is a blend space in the anim set (Locomotion), plus turn-in-place clips and optional orientation and stride warping (Character Visuals → Locomotion Warping).

18.2.3 Profiles: how the importer understands any pack

A profile (RSECharacterPackProfile, a data asset) is a list of name rules: patterns with wildcards or regular expressions. Rule groups: Characters (grouping by skeleton, prefixes to strip, target height), Animations (ordered rules pattern → slot, first match wins, extra matches become random variants), Anchors (socket names to find, then bones), Weapons, Strikes (hit frame and contact reach measured from the clip), Effects (role rules for Niagara, legacy particle systems and sounds), Colors (variants as material instances) and Character Data. A required slot that stays empty takes the fallback body's clip, retargeted when the skeleton differs. Missing anchors follow Character Visuals → Anchor Fallbacks (WeaponTip → HandRight, Muzzle → WeaponTip).

Three profiles ship in the plugin: DA_PackProfile_Generic, DA_PackProfile_LowPolyHumanoid (many characters on a shared skeleton, meshes only) and DA_PackProfile_HeroPack (several skins per skeleton, abilities named after their key). Start from a copy of the generic one and add rules until the dry run is right.

18.2.4 Styles and Dress My Abilities

A style (DA_AnimStyle_<Name>) says which clips fill which slots of an animation set and which clips abilities use. Apply Styles writes one animation set per skeleton (DA_AnimSet_<Style>_<Skeleton>) on top of the character's current one, retargets clips of other skeletons once and caches them. Dress My Abilities gives every ability or character that has no look a pose (strike, shot or cast) plus effects of the ability's element and role, and fills the battle-feel slots (weapon trail, cast, impact, projectile trail) and the status auras. The library remembers what it wrote (Provenance) and never overwrites a field you changed. Abilities from the plugin are never written: their dressed look goes to the characters instead.

What decides the effects is data. The Taxonomy (word rules for animations) and FX Taxonomy (element and role words, Dress Rules) can be duplicated and edited. After editing, press Reclassify.

18.2.5 Paired animations and finishers

Two montages that play together on two units, aligned and synced at one moment: finishers, synced counters and parries, boss grabs, boss phase moments. Pairs are presentation only; the rules already decided the result. A URSEPairedAnimationData asset holds the attacker and victim montages, the sync times, the relative position (distance, angle, victim yaw), alignment mode, motion-warp target, conditions (ability, weapon and target tags, outcome), a camera shot, slow motion and sync cues. A URSEPairedAnimationLibrary lists pairs, and Project Settings → Paired Animations registers libraries and sets frequency, chances, cooldown and side rules. The player's own choice is Options → Game → Finishers (Off / Sometimes / Always). In headless runs and with placeholder units the pair does nothing and the battle continues. Animation & FX Library → Find Paired Animations proposes pairs from clips with shared name stems (attacker/victim words), and Create Pairs builds the assets.

18.2.6 Portraits and icons

Portraits come from data, in this order: the character's Portrait Variants entry for the look variant, then Portrait, then generated art. Dialog portraits can be an image, a video clip, or a live 3D render, set on the speaker and overridable per line. The Portrait & Icon Studio renders portraits for characters and speakers from their looks, and icons for items, abilities and statuses, into textures it names T_Portrait_* and T_Icon_*. It is idempotent (a hash of its inputs decides whether to render again) and never replaces a texture you made by hand. Start it from RPG Saga → Content → Generate Portraits & Icons or right-click assets or a folder in the Content Browser; it shows a dry-run plan first.

18.3 Key classes and assets

Class / assetModuleRole
URSECharacterAppearanceRSEA look: parts, variants, Anim Blueprint, anim set, capsule, anchors, hold profile
FRSEAppearancePartSpecRSEOne part of a look (slot, mesh, socket, materials, weapon presentation, hold type)
URSEAppearancePartRSEA visible piece of equipment that replaces the part of the same slot
URSEAppearanceComponentRSEBuilds a look on an actor; forwards battle state and reactions to the animation
URSECharacterAnimSetRSEAnimation slots of one body
URSECharacterAnimInstanceRSEThe C++ base of every character Anim Blueprint
URSECharacterVisualSettingsRSEProject Settings → Character Visuals (body presets, fallback look, warping, performance)
URSECharacterScriptLibraryRSEEditorNewCharacterFromMesh and ImportCharacterPack for editor scripts
URSEAnimLibraryFunctionsRSEEditorThe Animation & FX Library nodes
URSEPairedAnimationData, URSEPairedAnimationLibraryRSEPaired animations and their libraries
URSEPairedAnimationLibraryFunctionsRSERuntime nodes: Find Pair, Play Paired Animation, Try Play Finisher
ARSEPortraitCaptureRigRSEThe rig the Portrait Studio renders

18.4 Settings

Project Settings → RPG Saga Engine. Full list: Appendix B.

  • Character Visuals: Body Presets, Anchor Fallbacks, Character Appearance Overrides (a look for characters you cannot edit, such as plugin example monsters), Fallback Appearance with team tint, Empty Slot Look, and animation values (Default Blend Time 0.2 s, Moving Speed Threshold 10 cm/s, turn-in-place rates, locomotion warping on by default, performance: update-rate optimization on, shadows on, Min LOD Bias 0).
  • Character Packs: Default Profile, Target Root (/Game/CharacterPacks), Body Preset Prefix, New Character Profile, New Character Default Class, Display Name Noise Words.
  • Animation & FX Library: Library Folder (/Game/AnimLibrary), Taxonomy, FX Taxonomy.
  • Paired Animations: libraries, finisher frequency and chances, alignment, camera, slow motion.
  • Generated Art and the Portrait Studio settings: output root (/Game/Generated by default), sizes, framing and light presets.

Body presets are written to DefaultGame.ini, which is shared. The importer therefore writes them only when Write Body Presets is on; by default each look carries its whole body and works in any project.

18.5 Blueprint usage

Character content is data, so most of the work is editor clicks. Nodes you reach for:

  • RPG Saga | Animation Library (Editor Utility Blueprints): Scan Folders, Reclassify Library, Auto-build Style, Build Style From Selection, Assign Style, Apply Style, Dress My Abilities, Summarize Library.
  • Paired animations (runtime): Find Pair, Play Paired Animation, Try Play Finisher, Compute Pair Alignment, Get Finisher Frequency, Set Finisher Frequency.
  • Portraits: Get Character Portrait, Get Icon, Get Speaker Portrait.

Example: a custom boss grab from Blueprint.

  1. In your boss graph: Make RSE Paired Context (fill in the kind and the ability, weapon and target tags) → Find Pair (Context = the result, Roll = Random Float).
  2. Is Valid on the returned pair.
  3. Is Valid → Play Paired Animation (Pair = the result, Attacker = the boss actor, Victim = the target actor, Local Camera = true, Victim Falls = false, On Finished = a custom event that continues your logic).

Add the RSE Appearance component to your own actor, set its Appearance (and Variant), and press Rebuild in the editor to preview the look in the viewport.

Components that put the plugin's systems on your own actors (RSE Interactable, RSE Explorer, RSE NPC Talk, RSE Door, RSE Combat Role, RSE Traversal, RSE Map Marker, RSE Night Light) are listed in docs/product/components.md. Any of them can be added in the Components panel of a Blueprint-only actor.

18.6 C++ usage

// Show a look on your own actor, then drive its animation.
UCLASS()
class AMyNPC : public ACharacter
{
    GENERATED_BODY()
    UPROPERTY(VisibleAnywhere) TObjectPtr<URSEAppearanceComponent> Look;
public:
    AMyNPC() { Look = CreateDefaultSubobject<URSEAppearanceComponent>(TEXT("Look")); }

    void BeginPlay() override
    {
        Super::BeginPlay();
        Look->SetAppearance(LookAsset, TEXT("Red"));          // soft ref + variant name
        Look->SetBattleState(ERSEAnimBattleState::Ready);
    }
};

Extension points: subclass URSECharacterAnimInstance for custom animation logic (the shipped Anim Blueprints then keep working); resolve anchors with ResolveAnchor and GetAnchorLocation when you spawn your own effects; add new part slots and anchors as Gameplay Tags.

18.7 Advanced

  • Command line. UnrealEditor-Cmd <Project>.uproject -run=RSECharacterPack -Source=/Game/Pack [-Target=<folder>] [-Profile=<object path>] [-DryRun] [-WritePresets] [-NoVariants] [-NoPresentations] [-NoCharacterData] [-NoRetarget] [-TextureGroups] [-LowMinLOD=<n>]. Portraits: -run=RSEPortraitStudio -AllowCommandletRendering [-Paths=...] [-Output=...] [-Force] [-DryRun], or -ExecCmds="RSE.PortraitStudio.Generate,QUIT_EDITOR" when you need the editor's font renderer for template icon letters.
  • Meters-scaled rigs. Rigs exported with the root bone scaled by 100 are detected and corrected automatically; the report prints a Note per corrected batch.
  • Grips. On bare hand bones the importer's Auto Grip computes how each weapon is held; a Grip Reference mesh gives the direction. The result is editable data on the look part.
  • Handheld performance. Two optional importer switches move textures to the Character texture groups and give the Low quality level a minimum LOD; enable per-quality-level minimum LODs for skeletal meshes in the project for the latter.
  • Retargeting. Borrowed clips play in place (root motion extracted) and lose the other pack's particle notifies; sounds stay. Retargeting works best between humanoid skeletons.
  • Debugging pairs. RSE.Paired.Disable 1 stops every pair; RSE.Paired.ForceFinishers 1 makes every kill with a fitting pair play it (2 also ignores Options Off). RSE.Studio.PairCapture <Dir> Asset=<pair> captures store-page frames.

18.8 Troubleshooting

SymptomCauseFix
The character is invisible or a pointRig exported in metersUpdate the plugin and import again; the report names the corrected batch
Twisted arms or sliding feetRetargeting a fallback onto an unusual rigUse the pack importer with its own animations and tune the profile rules
Knock-outs look bentThe pack's death clips end in a ragdoll lead-inMap a better clip or keep the fallback
An attack has no effects or soundsEffects are paired by name and the names are unrelatedAdd effect rules to your profile; the dry run lists unmatched effects
A weapon went to the wrong characterShared folderAdd a rule with a Characters pattern, or enable Match Assets By Name
A clip is in the wrong categoryName or measurement misled the classifierSelect it, pick the category, press Set. It stays Manual
A plugin look did not changePlugin content is a templateCopy the look into your project first
An ability kept its old lookThe library never overwrites your editsClear the ability's presentation and dress again
The character is too big or smallModel scaleSet Target Height and create it again

18.9 See also