Owen/MULTI_SCHEME_GUIDE.md

Multi-Scheme Animation Naming Guide

The Owen Animation System supports four different naming schemes to accommodate different workflows and preferences. This guide explains each scheme and how to use them effectively.

🎯 Overview

The multi-scheme animation naming system provides backward compatibility while making the Owen Animation System more accessible to different types of users:

• Legacy Scheme: Original technical format for backward compatibility
• Artist Scheme: Blender-friendly names for 3D artists
• Hierarchical Scheme: Organized dot-notation for structured projects
• Semantic Scheme: Readable camelCase for developers

📝 Naming Schemes

1. Legacy Scheme (Technical/Backward Compatible)

Format: {state}_{emotion}_{type} Examples:

• wait_idle_L - Wait state, idle animation, Loop
• react_an2type_T - React state, angry to type, Transition
• type_idle_L - Type state, idle animation, Loop
• sleep_2wait_T - Sleep state, to wait transition, Transition

Use Cases:

• Existing Owen implementations
• Technical documentation
• Legacy animation files

2. Artist Scheme (Blender-Friendly)

Format: Owen_{Action} or Owen_{StateAction} Examples:

• Owen_WaitIdle - Wait idle animation
• Owen_ReactAngryToType - React angry to type transition
• Owen_TypeIdle - Type idle animation
• Owen_SleepToWait - Sleep to wait transition

Use Cases:

• 3D artists working in Blender
• Animation asset naming
• Non-technical team members
• Clear, human-readable names

3. Hierarchical Scheme (Structured/Organized)

Format: owen.{category}.{state}.{detail}.{type} Examples:

• owen.state.wait.idle.loop - Wait state idle loop
• owen.state.react.angry.totype.transition - React angry to type transition
• owen.state.type.idle.loop - Type state idle loop
• owen.state.sleep.towait.transition - Sleep to wait transition

Use Cases:

• Large projects with many animations
• Structured asset organization
• Configuration files
• Automated tooling

4. Semantic Scheme (Developer-Friendly)

Format: Owen{StateAction}{Type} (PascalCase) Examples:

• OwenWaitIdleLoop - Wait idle loop animation
• OwenReactAngryToTypeTransition - React angry to type transition
• OwenTypeIdleLoop - Type idle loop animation
• OwenSleepToWaitTransition - Sleep to wait transition

Use Cases:

• JavaScript/TypeScript code
• API integration
• Developer constants
• Type-safe programming

🔧 Usage Examples

Basic Usage

import { OwenAnimationContext, convertAnimationName } from './owen-animation-system';

// Get animation using any naming scheme
const clip1 = owenContext.getClip('wait_idle_L');           // Legacy
const clip2 = owenContext.getClip('Owen_WaitIdle');         // Artist
const clip3 = owenContext.getClip('owen.state.wait.idle.loop'); // Hierarchical
const clip4 = owenContext.getClip('OwenWaitIdleLoop');      // Semantic

// All return the same animation clip!

Name Conversion

import { convertAnimationName, getAllAnimationNames } from './owen-animation-system';

// Convert between schemes
const artistName = convertAnimationName('wait_idle_L', 'artist');
// Returns: 'Owen_WaitIdle'

const semanticName = convertAnimationName('Owen_ReactAngry', 'semantic');
// Returns: 'OwenReactAngryLoop'

// Get all variants
const allNames = getAllAnimationNames('react_an2type_T');
/* Returns:
{
  legacy: 'react_an2type_T',
  artist: 'Owen_ReactAngryToType',
  hierarchical: 'owen.state.react.angry.totype.transition',
  semantic: 'OwenReactAngryToTypeTransition'
}
*/

Validation

import { validateAnimationName } from './owen-animation-system';

const validation = validateAnimationName('Owen_WaitIdle');
/* Returns:
{
  isValid: true,
  scheme: 'artist',
  error: null,
  suggestions: []
}
*/

const invalidValidation = validateAnimationName('invalid_name');
/* Returns:
{
  isValid: false,
  scheme: 'unknown',
  error: 'Animation "invalid_name" not found',
  suggestions: ['OwenWaitIdleLoop', 'OwenReactIdleLoop', ...]
}
*/

Using Constants

import { 
  LegacyAnimations, 
  ArtistAnimations, 
  SemanticAnimations 
} from './owen-animation-system';

// Type-safe animation references
const legacyAnim = LegacyAnimations.WAIT_IDLE_LOOP;        // 'wait_idle_L'
const artistAnim = ArtistAnimations.WAIT_IDLE;             // 'Owen_WaitIdle'
const semanticAnim = SemanticAnimations.WAIT_IDLE_LOOP;    // 'OwenWaitIdleLoop'

🎨 Workflow Integration

For 3D Artists (Blender)

1. Use Artist Scheme names when creating animations in Blender
2. Name animations like Owen_WaitIdle, Owen_ReactHappy, etc.
3. Export animations with these names
4. The system automatically handles conversion to other schemes

For Developers

1. Use Semantic Scheme constants in code for type safety
2. Import animation constants: import { SemanticAnimations } from './owen-animation-system'
3. Reference animations: SemanticAnimations.WAIT_IDLE_LOOP
4. Let the system handle backward compatibility

For Project Management

1. Use Hierarchical Scheme for asset organization
2. Structure animation files: owen.state.{stateName}.{details}.{type}
3. Easy filtering and categorization
4. Clear project structure

🔄 Migration Guide

From Legacy to Multi-Scheme

// Before (Legacy only)
const clip = owenContext.getClip('wait_idle_L');

// After (Multi-scheme compatible)
const clip = owenContext.getClip('wait_idle_L');           // Still works!
// OR use any other scheme:
const clip = owenContext.getClip('Owen_WaitIdle');         // Artist-friendly
const clip = owenContext.getClip('OwenWaitIdleLoop');      // Developer-friendly

Updating Animation Assets

1. No changes required - existing legacy names continue to work
2. Gradual migration - add new scheme names alongside legacy names
3. Full migration - replace legacy names with preferred scheme

📚 Available Animations

Wait State

Legacy	Artist	Semantic
wait_idle_L	Owen_WaitIdle	OwenWaitIdleLoop
wait_pickNose_Q	Owen_PickNose	OwenQuirkPickNose
wait_stretch_Q	Owen_Stretch	OwenQuirkStretch
wait_yawn_Q	Owen_Yawn	OwenQuirkYawn

React State

Legacy	Artist	Semantic
react_idle_L	Owen_ReactIdle	OwenReactIdleLoop
react_an_L	Owen_ReactAngry	OwenReactAngryLoop
react_sh_L	Owen_ReactShocked	OwenReactShockedLoop
react_ha_L	Owen_ReactHappy	OwenReactHappyLoop
react_sd_L	Owen_ReactSad	OwenReactSadLoop

Type State

Legacy	Artist	Semantic
type_idle_L	Owen_TypeIdle	OwenTypeIdleLoop
type_fast_L	Owen_TypeFast	OwenTypeFastLoop
type_slow_L	Owen_TypeSlow	OwenTypeSlowLoop

Sleep State

Legacy	Artist	Semantic
sleep_idle_L	Owen_SleepIdle	OwenSleepIdleLoop
sleep_2wait_T	Owen_SleepToWait	OwenSleepToWaitTransition

🛠️ API Reference

Core Methods

getClip(name: string)

Get animation clip by name (supports all schemes)

getClipByScheme(name: string, targetScheme: string)

Get animation clip with specific scheme conversion

convertAnimationName(name: string, targetScheme: string)

Convert animation name between schemes

getAllAnimationNames(name: string)

Get all scheme variants for an animation

validateAnimationName(name: string)

Validate animation name and get suggestions

Constants

NamingSchemes

• LEGACY: 'legacy'
• ARTIST: 'artist'
• HIERARCHICAL: 'hierarchical'
• SEMANTIC: 'semantic'

Animation Constants

• LegacyAnimations: Legacy scheme constants
• ArtistAnimations: Artist scheme constants
• HierarchicalAnimations: Hierarchical scheme constants
• SemanticAnimations: Semantic scheme constants

🎯 Best Practices

1. Consistency: Choose one primary scheme for your team and stick to it
2. Type Safety: Use constants instead of raw strings when possible
3. Documentation: Document which scheme you're using in your project
4. Validation: Use validateAnimationName() to catch typos early
5. Migration: Plan gradual migration for existing projects

🚀 Examples

Check out the Mock Demo for interactive examples of:

• Name conversion between schemes
• Animation validation
• Real-time scheme testing
• Integration patterns

---

For more information, see the main README or check the API documentation.