Luna UI Documentation

com.cupkekgames.character — humanoid character primitives. Bundles model spawn, animation engine, blend-shape expressions, eye movement, and slot-based accessories into a single CharacterFeature you attach to any Unit. All visual sub-systems use string kinds so domain games extend the catalog without forking the package.

CharacterFeature on a Unit

CharacterFeature is the IUnitFeature that wires a Unit to its 3D presence:

csharp

unit.AddFeature(new CharacterFeature());
// after spawning the prefab via your pool/scene:
unit.GetFeature<CharacterFeature>().SetCharacter(spawnedGameObject);

var feature = unit.GetFeature<CharacterFeature>();
feature.AnimationController.Play(AnimationKinds.Idle);
feature.BlendShapeController.SetExpression(BlendShapeKinds.Joy);

The feature exposes the resolved sub-systems (AnimationEngine, AnimationController, BlendShapeController, EyeMovement) so callers route through one entry point. The matching CharacterDefinition (an IUnitFeatureDefinition) carries the prefab reference (ModelCharacterSO) on the unit's UnitDefinitionSO.

Kind-driven visuals

Three open string-kind catalogs cover the visual vocabulary:

BlendShapeKinds — facial expressions (Neutral, Angry, Fun, Joy, Sorrow, Surprised, Smug, Love, HeartBreak). Keyed by BlendShapeDatabase / BlendShapeDatabaseVFX.
AnimationClipKinds — character clips (Walking, Waving, Talking01, JumpForJoy, Cheer1, Mining, ChestOpen, …). Keyed by AnimationDatabase.
VisualAccessoryRoleKinds — accessory slot roles (DEFAULT, MINING). Saved on CharacterVisualAccessory.Role so a single mesh can be authored once and re-bound per gameplay context.

Domain games add new kinds by populating their database assets. Framework code uses these constants as the standard slots; nothing prevents game-specific values.

Sub-systems

HumonoidCharacter (MonoBehaviour, on the prefab) — entry point. Resolves BlendShapeController, IAnimationStateController, IAnimationEngine, EyeMovement from children. Exposes Head, EmotionTarget transforms.
BlendShapeController + BlendShapeDatabase / BlendShapeDatabaseVFX — kind-keyed expression blending. BlendShapeListBlend blends multiple shapes simultaneously; auto-blend helpers under BlendShapes/Auto/.
AnimationDatabase + AnimatorControllerLayerDatabase — kind-keyed clip lookup, layered controllers.
EyeMovement — natural saccade-style look-at driven by a target transform.
CharacterVisualAccessories + CharacterVisualAccessory — slot system for swappable equipped meshes (hats, tools, weapons) keyed by role.
ModelCharacterSO — the SO wrapper around the character prefab reference, held on CharacterDefinition.
Particles + Timeline integrations under Particles/ and Timeline/ for emote VFX and authored animation timelines.

What's inside

HumonoidCharacter — top-level character component
CharacterFeature (IUnitFeature) + CharacterDefinition (IUnitFeatureDefinition)
ModelCharacterSO
BlendShapeController, BlendShapeDatabase, BlendShapeDatabaseVFX, BlendShapeListBlend, auto-blend helpers
AnimationDatabase, AnimationClipKinds, AnimatorControllerLayer, AnimatorControllerLayerDatabase
EyeMovement
CharacterVisualAccessories, CharacterVisualAccessory, VisualAccessoryRoleKinds
BlendShapeKinds
Combat / Particles / Timeline integration folders

Asmdef + namespace

CupkekGames.Character (runtime).

Dependencies

com.cupkekgames.units (for IUnitFeature + UnitView)
com.cupkekgames.animations (for IAnimationStateController + AnimationKinds)
Plus the foundation set used by HumonoidCharacter: services, timesystem, addressableassets, scenemanagement, sequencer, settings, gamesave, vfx

Repository

Cupkek-Games/CupkekGames-Character