Semantics of Animation Scenes (alpha) 0.5.0

SoAS introduces rich meta information for animations played by AAF/NAF.

Semantics of Animation Scenes

Disclaimer: Project is far from finished. Some parts may not work properly. Crashes are possible. At this stage it can be considered as announcement of upcoming features.

Project is designed for defining and obtaining in the scripts bunch of information related to animations played by AAF/NAF.

This tool consist of multiple parts:

1) Data\Scenes\tools\ScenesEditor.exe - visual editor of information associated with animation scenes

2) Data\Scenes\tools\AAFXmlScanner.exe - visual tool for detecting potential errors in AAF XML files 

3) Data\Scenes\Default - default set of data. 

4) Data\F4SE\plugins\SoAS.dll - F4SE plugin that holds information assiciated with animations.

5) Data\Scripts\SoAS.pex - Papyrus script with API to get access to information held by F4SE plugin.

Key features:

1) Rich information about animation itself, about participants, about contacts between participants and environment can be defined and obtained.

2) F4SE plugin supports dynamic custom Papyrus structs populating. At this moment boolean fields that represents some specific flags are supported. See below.

3) Visual editor of information related to scenes/participants/contacts

How data accessing works:

At the game start F4SE plugin initiates background reading of information from files located in  Data\Scenes. When it is successfully finished F4SE pluigin is able to provide this information via Papyrus script API. 

F4SE plugin is able to reload this information during game play via console by command:

cgf "SoAS.StartDataReload"

NOTE: Do not call this method from a Papyrus script.

During data reloading all calls of Papyrus API are failing until reload done.

How data defined:

1) ScenesEditor is able to import animations, positions, groups, trees and tags data from AAF XML files. It is able to categorise tags and make a guess what these tags may mean. Guesses reflected as participant's and contacts attributes. Also tags falls to multiple categories. Consider it as semi-automation of participants and their contacts defining. NAF data import is not supported yet as it is not finalized. 

2) User of ScenesEditor is able to define:

  - tags (and its category) for the scene. 

  - participant's attributes

  - contacts between participants and between participant and environment.

  - select the area of participant's contact. multiple creatures are supported

  - attributes of defined contacts

  - custom scene attributes as an object, not a plain string. 

3) When edit finished, data can be exported as a zip package ready to upload.

Notes for the initial version (0.5.0):

Ability to add scene is not supported yet. Import only is supported. There is the problem of animation's participants validation, so this feature is postponed. 

Not all creatures are supported yet. List of supported creatures can be found in Data\Scenes\docs

Default data set is shipped along with binary files. Later default data set and binary files will be released separately.

Default data set populating is barely started. It will be populated over time

Scene's custom attributes obtaining is not implemented yet.

Source code is available on github

Default data set source is available on github

Code sample how to obtain contacts information in a Papyrus script:

Scriptname MyGlobalTests hidden

import SoAS
function TestContacts1() global
    ParticipantsContact[] contacts = GetParticipantsContacts("Gray Spanking 02 Staged") as ParticipantsContact[]
    Debug.Trace(contacts)
endfunction

struct CustomActorsContact
    Actor From_Participant
    string From_Area
    int From_Stimulation
    int From_Hold
    int From_Pain
    int From_Comfort

    bool From_Is_Left_Hand
    bool From_Is_Hand
    bool From_Is_Right_Hand

    bool From_Is_Left_Arm
    bool From_Is_Arm
    bool From_Is_Right_Arm

    Actor To_Participant
    string To_Area
    int To_Stimulation
    int To_Hold
    int To_Pain
    int To_Comfort
    bool To_Is_Butt
    bool To_Is_Vagina
endstruct

function TestContacts2() global
    Actor[] participants = new Actor[2]
    participants[0] = Game.GetPlayer()
    participants[1] = Game.GetPlayer()
    CustomActorsContact[] contacts = GetParticipantsContacts("Gray Spanking 02 Staged", "MyGlobalTests#CustomActorsContact", participants) as CustomActorsContact[]
    Debug.Trace(contacts)
endfunction

Please note for the structure CustomActorsContact. It contains boolean fields like From_Is_Left_Hand, To_Is_Butt and so on.

It is the part of custom structures population feature. Fields that meet following naming convention are automatically calculated and populated:

{From|To}_Is_{AreaName}

From or To - the keyword to define direction of the contact. Value from outcoming (or incoming) participant's contact is assigned.

Is - the keyword to define a flag field

AreaName - one of the allowed contact area names. Allowed contact area names can be found in the files in Data\Scenes\docs

The value of such flag is calculated according to body parts hierarchy.

An example for humanoid creature:

Lets assume we have the Hand contact area selected for Left Arm body part. In this case flags will be: Is_Left_Hand=true, Is_Arm=true, Is_Left_Arm=true, but Is_Right_Hand=false.

Another example for brahmin that have 2 heads:

Lets assume we have Ear contact area selected for Right Head body part. In this case flags will be: Is_Right_Ear=true, Is_Right_Head=true, Is_Head=true

More documentation and code samples will be added over time.

Your feedback is welcome. Don't hesitate to share your thoughts in comments and on related github issues page.

You are welcome to take a part in default data set populating. I will update ScenesEditor soon to make the work easier.

Credits

--