Data model proposal

[dlinny-lag]

The problem: Currently using data model seems not flexible enough to cover multiple use cases.

Known problems caused by current model: 1) Attempt to add a morph (or action, for example) to an existing animation causes necessity to alter (or create new) animation definition object. If alteration is choosen, the original animation definition is lost, so to avoid original definition loss people prefer to create new animation definition. Solution that was used - create new animation definition with necessary adjustments and add a position definition that refer to the new animation definition. Ultimately new position is created in any way as it seems reasonable to allow gamers to select position with or without adjustments. In the end - mod makers are forced to create new animation definition when new position is required only. It seems more sutable to have an ability to add "adjustments" without alteration of animation definition. 2) In the current model position may refer to animation, animation group and positions tree. This leads to increased probability of mistake as the reference points to incompatible objects. It should be better to have more strongly typed references. 3) Tags theirselves are good, but tags are not enough to define all required custom attributes for positions. They are good for filtering operations, but insufficient to define complex attributes. There are a few attempts to encode additional information to tags, because of lack of support in data model. It should be better to have an ability to define custom complex attributes for positions in addition to tags. I.e. ability to declare objects as attributes where plain strings are not enough. 4) It is not possible to define individual set of tags for animations in animation group. It should be better to have an ability to define custom attributes to animations in a group as the animations in a group may have significant difference in meaning.

Following incomplete data model in pseudo-code is proposed:

class AnimationDefinition 
{
    string Id; 
    string Reference; // somehow link .hkx file or IDLE object
    string Skeleton; 
    float Duration; // debatable
}
class Adjustment
{
    // supposed derived classes are : Action, Morph
    // subject to clarify
}
class AnimationParticipantDefinition
{
    string AnimationDefinitionId;
    enum Sex; // M,F,P
    TransformMatrix Transform; // offsets and rotations could be defined differently
    (debatable) Adjustment[] Adjustments;
}
class Animation
{
    string Id;
    AnimationParticipantDefinition[] Actors;
    (debatable) Adjustment[] Adjustments;
}
class Scene
{
    string DisplayName;
    string AnimationId;
    string FurnitureTypeId; // simplified. there options how to define and use
    Adjustment[] Adjustments; // simplified. there are options how to link adjustments with actors
   // custom attributes and tags may defined outside of the scene object
}
class ScenesGroup
{
    string DisplayName;
    Scene[] Scenes;
}
class ScenesTree
{
    string DisplayName;
    Tree<Scene> Scenes;
}

Note: Furniture definition is out of scope for the moment, but it is expected that furniture definition will include details to transform actors to make them aligned to particular furniture.

Major differences: 1) Scenes group instead of animations group. 2) Adjustments moved to the scene level.

Expected problem: 1) Alignment to furniture is not clarified. It seems usefull to have an ability to play single animation on multiple furniture objects that have different geometry. 2) Due to huge amount of potential adjustments combinations amount of scenes may insanely grow in gamer's environment. It should be better to find some solution for gamers to manage huge amout of scenes.

Expected benefits: 1) Dev community may get library of "clean" animations that can be used for different purposes. 2) Dev community may get library of adjustments, that can be used in mods and scenes packs. 3) Animation creators could apply less efforts to release new animations. 4) Animation creation, adjustments creation and scenes creation processes can be detached, so it may cause more mod makers to be interested in the work.

This proposal does not pretend to be complete at this moment. This proposal made in hope that it will be completed during further discussions.

[Deweh]

While this proposal is good, it seems to still be too similar to the data layout used by AAF. The current draft of NAF's data layout is as follows:

NAF will utilize the concept of inheritance to make extensibility as intuitive as possible. Each data entry can be specified as one of the following: base, inherit, extend.

base means that the data entry is completely unique and does not inherit or extend anything else. inherit means that the data entry is automatically populated with everything from the indicated entry, and can change or add specific parts. extend means that the data entry modifies the indicated entry, and all added data will be tacked on to the original.

The data types are as follows:

commandLists are a list of commands (executable functions) and parameters that can be ran when certain events occur. There are special JumpIfTrue and JumpIfFalse commands that can check a certain variable and jump to a different execution point in the command list, as defined by DefineJumpPoint. controlSystems are the bread and butter of customizing scenes. They can specify commandLists to be ran on system begin, system end, and anim loop. controlSystems can also define (a limited number) of custom variables that can be used in combination with the commandLists to keep track of state. graphTypes define how NAF should handle each type of behavior graph in the game. presets are the base data type that animators will want to add. They define the idle/hkx, graphType, and gender of each participant. They can also specify a commandList to execute when the preset begins/ends, as well as a default controlSystem, which can be overriden via the Papyrus API if one would like to use a different controlSystem than the preset's default.

This first draft is of course open to feedback.

[dlinny-lag]

Ok, I will list the features I would expect from the framework

For animation creator:

• Simple way to define animation unit. Having hkx/idle just add a few lines of metadata - id, skeleton and maybe something else (root behavior graph? start event?). Custom attributes would be great.

For animations pack creator:

• Simple way to define a directed graph of animation units (I would prefer to name it Scene, will use it below) that has seamless transitions between units. I mean, combine multiple animations of multiple participant to a seamlessly playing scene. I belive that declarative approach is more suitable than a procedural approach you propose, as animation and pack creators often are not developers.
• Ability to define speed and duration for each unit in a Scene. It would be great if some synchronization routines will be available out of box.
• Ability to adjust xyz-offset and rotation for each unit in Scene.
• Automatic offset/rotation adjustment when furniture is used in Scene
• Ability to define custom event
• Ability to attach custom event to the particular animation unit in Scene.
• Framework should trigger registered custom events when Scene playing engine starts/finishes certain unit.
• Ability to attach custom attributes to the Scene. Attributes can be used for searching/filtering. Some predefined set of attributes would be useful, like Authors, Version, Tags, etc.

For animation focused mod developer:

• Ability to define semantics for Scene. Not sure that it should be a part of NAF, but would be great.
• Ability to register custom event
• Ability to attach custom event to the particular animation unit in Scene.
• Ability to build and register a Scene from animation units by Papyrus script. Possibly from higher building blocks than animation unit.
• Routines like equip/unequip, add/remove overlay, set/reset morph should be executed by framework. Ability to invoke these routines in custom event handler (I don't think that it will be a good idea to support Papyrus event handlers here).
• Ability to animate morph parameters change. Would be great.

For a developer of animations user mod:

• Ability to search for Scenes by various search criteria. It would be great if details of semantics can be used as a search criteria.
• Ability to start Scene playing with play parameters
• Ability to stop Scene playing.
• Ability to receive custom events in Papyrus script. In addition to predefined events.
• Ability to request actor's state
• Ability to receive actor's state change notification
• Ability to request currently playing Scenes
• Ability to request playing scene details, like actors and attributes. (semantics would be great)

Note for "ability to attach" or "ability to register". It is required to attach/register something without alteration of existing declaration (if they are). Otherwise you can expect a lot of conflicts in the files where entries are declared. Note about events. I suppose there are should be 2 types of events. Some events have to be fired in a way to be processed by Papyrus scripts, some events could be handled by framework itself.

[dlinny-lag]

base means that the data entry is completely unique and does not inherit or extend anything else. inherit means that the data entry is automatically populated with everything from the indicated entry, and can change or add specific parts. extend means that the data entry modifies the indicated entry, and all added data will be tacked on to the original.

As I understand it is the idea how to organize entries in the files with entries declarations. I would suggest to think about namespaces or prefixes that can be inherited. I think it will be necessary on the later stages when amount of scenes that a gamer may choose from becomes huge.

[dlinny-lag]

Some note about custom attributes attached to the scene/actors. I'm preparing a solution to deal with custom attributes. Solution doesn't require NAF/AAF installation and attributes matched to the scene by scene name. So requests

• Ability to attach custom attributes to the Scene. Attributes can be used for searching/filtering. Some predefined set of attributes would be useful, like Authors, Version, Tags, etc.
• Ability to define semantics for Scene. Not sure that it should be a part of NAF, but would be great.
• Ability to request playing scene details, like actors and attributes. (semantics would be great)

are no longer actual.