Need for guidance/clarification with the ArticyFlowPlayer

Wed 31. Jul 2019, 13:33

Hey there,

First of all, I think the "bridge" between Articy and Unity is a great thing, thanks so much for this plugin!
I started fiddling around with the Articy Unity Importer and I think I need some clarification and/or guidance.
Now, I watched all the videos related to the Unity Importer, I looked at the documentation/guides and of course I downloaded and looked at (and still looking while writing this down) the Maniac Manfred Demo.
You written guide/documentation is great and I get the way I can handle the data I get from Articy. All information is listed there, nice, I already could successfully handle the articy objects.
My problem comes down to this: the ArticyFlowPlayer.

Currently I don't know if I want to use the ArticyFlowPlayer since I find it a difficult to wrap my head around the way it needs to be setup/the way it works. The Maniac Manfred demo is not a big help if I have to be honest, well it is of course, I can look at it, study the code and how that project is setup. Saying that it would be great if there would be more tutorials or more examples like that Maniac Manfred, but in smaller scope.
I imagine a simple scene which does basically nothing more than registering user input to traverse a dialogue. Like show what needs to be setup for a bare minimum flow traversal, like a simple non-branching dialogue and then what needs to be done for a branching dialogue.

As of now the Maniac Manfred Demo is a bit confusing, which leads to these questions:

- Can a single Unity scene have more than one ArticyFlowPlayer-Component? Would I want that, Is that a valid use-case?
- Is is valid to attach the ArticyFlowPlayer at runtime via AddComponent only when I need it and remove it when not needed?
- The ArticyFlowPlayer has methods like .Play(), which kind of implies that there are other functions like Pause()/Resume() or Stop(), but there aren't. Can I actually stop the flow?
- The SceneHandler.cs is responsible for all of the game logic at least how things traverse. In order to actually traverse there needs to be a very specific funtion that does so, in this case it's the ContinueFlow-Method, right? This Method is
custom though, it's not an implemented method of the IArticyFlowPlayerCallbacks interface. Do I understand it right that what this function essentially does in that example is this:
flowPlayer.StartOn = aObject;

And I guess this is the gist of it: Setting the .StartOn property in order to dictate at which point the Flow will start/from where it will traverse until it reaches an end, and at some specific points you got to control the flow with the methods of the FlowPlayer (like Play()) ?


Edit: Oh and while am at it: how does the Debugging actually work, what does the "Attach to articy:draft"-Button exactly do?

Edit 2: Is it possible there is a bug with the "Ignore invalid Branches"-Flag or is my code/setup just wrong.

0) The "Ignore invalid Branches"-Flag is set to true
1) In my articy project there is an empty FlowFragment transitioning to a Dialogue with an InputPin and a condition where it checks if a specific variable is == true. This variable was set to true by default.
2) I made a simple script which looks like this:

Code: Select all
 public class DialogueTest : MonoBehaviour,
                                     IArticyFlowPlayerCallbacks
    {
        public TextMeshProUGUI textMesh;

        public ArticyFlowPlayer flowPlayer;


        public void OnFlowPlayerPaused(IFlowObject aObject)
        {
            if (aObject is IDialogue)
            {
                flowPlayer.Play();
                return;
            }


            var dlgFragment = aObject as DialogueFragment;
            if (dlgFragment != null)
            {
                textMesh.text = dlgFragment.Text;
            }
        }

        public void OnBranchesUpdated(IList<Branch> aBranches)
        {
        }

        [Button]
        void ContinueFlow()
        {
            flowPlayer.Play();
        }
    }



3) I set that very first FlowFragment as the StartOn Property in the Inspector.
4) When I hit the ContinueFlow-Button in my inspector it traverses to the next FlowObject, hitting again it reaches the dialogue and shows up the correct text until there are no FlowObjects to traverse to.
5) Now, when I set the global variable to false in the DataBase I expect the FlowPlayer to still go through all the FlowObjects when I hit my ContinueFlow-Button since it should "ignore invalid Branches" which means my condition, which was set to false is invalid, but we're ignoring it, right? => It does not.
When hitting the ContinueFlow-Button the Player it stops right before that dialogue.

Is this behaviour with that flag intended or did I misunderstand that functionality, if so: what's the purpose? And is there a way to "brute force" through the Flow?
User avatar
btsslawa
 
Posts: 17
Joined: Fri 21. Aug 2015, 10:14

Re: Need for guidance/clarification with the ArticyFlowPlaye

Wed 31. Jul 2019, 16:20

Hi btsslawa,

first, thank you for your kind words! :)

I can understand that the FlowPlayer can be a bit tricky, but i will try to help you with it.
Most of the complexity of the FlowPlayer stems from the fact, that i wanted it to keep it as flexible as possible. This obviously comes at the cost of generalization.

So let me first summarize what the Flow player does for you: Traversing the flow; calling the scripts on the pins and logic nodes; updating global variables; evaluating conditions to select the correct path in cases of branches and finally present you objects you want to do something with and help in cases where the flow player can't select a unique path (usually multiple choice).

That also means, the flow player doesn't take care of input, visualization, animation, sounds etc. etc. It is the backend or engine for a dialogue system, you need to write, so to speak.

That out of the way, let me address your questions:

- Can a single Unity scene have more than one ArticyFlowPlayer-Component? Would I want that, Is that a valid use-case?


Yes absolutely. And if you want to do that is up to you. The flow player is just a traversal engine through your flow, if it makes sense
to have multiple "traversals" simultaneously or multiple at different places is up to you.
But in general: No, i don't think it's needed and in most cases a single one is enough.

- Is is valid to attach the ArticyFlowPlayer at runtime via AddComponent only when I need it and remove it when not needed?


Sure, you can even attach it to a prefab and create it and destroy as you like. The only information you might want to store, is the current object where the flow player is paused. All variables changed are stored in the GlobalVariables container anyway.

- The ArticyFlowPlayer has methods like .Play(), which kind of implies that there are other functions like Pause()/Resume() or Stop(), but there aren't. Can I actually stop the flow?


We picked this analogy because the flow player will pause for you. Think of the flow player as a pointer into your flow, after setting a start object(where your pointer starts). It will visits all the nodes, pins and following the connections. In case of branches, the conditions are checked; and if a unique path could be found and it will continue traverse that. This is done in milliseconds. This hopefully explains, why there can't be a manual Stop or Pause, you must be rather quick to hit what you would want to hit. :)

Now the flow player will pause in two occasions:
The first one is, it can't select a unique path. This is simply the case where you have multiple valid branches. In the case where the flow player found multiple valid branches, it pauses and gives you all encountered branches via OnBranchesUpdated. It will pause until you tell the flow player to continue by passing one of the given branches into the Play() method, basically telling it "Yeah, follow branch no. 3". How you pick that branch is up to your use case, most of the times you would present them in the ui as a multiple choice dialog. But for barks or random chatter selecting a random branch can be fun.

And the other pause happens if the flow player, while visiting, hits something we call a pause target. A pause target can be any articy object type that the flow player could encounter while traversing(FlowFragment, DialogueFragment, Pins etc.). When he finds a pause target, it pauses traversal, gives you the object via OnFlowPlayerPaused and waits for you to call Play() again.
For example: You need to show DialogueFragments in the UI? Make DialogueFragment part of the pauseOn list, then when OnFlowPlayerPaused is called, read everything you need from the DialogFragment instance, display it any way you want and once finished call Play() again and let the FlowPlayer resume.
You have placed a special Template on your Hubs? Make Hub a pause target, parse the template, calculate or call other code and directly call Play() in the same frame again.

- The SceneHandler.cs is responsible for all of the game logic at least how things traverse. In order to actually traverse there needs to be a very specific funtion that does so, in this case it's the ContinueFlow-Method, right? This Method is
custom though, it's not an implemented method of the IArticyFlowPlayerCallbacks interface. Do I understand it right that what this function essentially does in that example is this:
flowPlayer.StartOn = aObject;


This is specific to maniac manfred and is just a generic way to deal with different reference slots in various objects templates. If its an entity, its probably an item, and we used it to give the item to the user (Not really flow related, i know). If it is a location we just chance scenes and going to a new location. And finally every other thing would start a dialogue.
Don't think to much about it tho, this is how the designer decided to create the templates and overall structure and this method was a general way to deal with different kind of situations.

And I guess this is the gist of it: Setting the .StartOn property in order to dictate at which point the Flow will start/from where it will traverse until it reaches an end, and at some specific points you got to control the flow with the methods of the FlowPlayer (like Play()) ?


Basically yes. It might help to think that the flow player is greedy and wants to traverse as long as it can, it will only pause if we told it beforehand via pauseOn or if it can't decide on its own.

Edit: Oh and while am at it: how does the Debugging actually work, what does the "Attach to articy:draft"-Button exactly do?


Open articy:draft with the project you used to export. Open the flow. Select in unity the flow player while playing the game, hit attach. Now the flow player will send the current pause to articy:draft, which allows you to follow the flow in it, or use the model sheet to see the data in it.

Edit 2: Is it possible there is a bug with the "Ignore invalid Branches"-Flag or is my code/setup just wrong.
...
When hitting the ContinueFlow-Button the Player it stops right before that dialogue.
Is this behaviour with that flag intended or did I misunderstand that functionality, if so: what's the purpose?


Thats is correct. The wording is just a bit weird i guess. Usually you don't care for invalid branches (aka "branches where the condition evaluated to false, making the invalid to traverse"). You wouldn't
want the user to select a dialogue choice, where the script decided that it is not a valid option. But it can make sense for debugging purposes to show it anyway, and thats what this flag does.

And is there a way to "brute force" through the Flow?


What do you mean by that? You could parse the flow by hand, picking connections manually, but this is incredibly cumbersome to type and nothing really is gained i think. The flow player is pretty fast and almost everything can be achieved by utilizing the available options.

Phew, lot of text :) Let me know if anything is still unclear and i glady try to clear it up

Best regards

Nico
Nico Probst
Senior Software Engineer | Articy | LinkedIn
User avatar
[Articy] Nico Probst
Articy Staff
Articy Staff
 
Posts: 217
Joined: Wed 23. Nov 2011, 09:45
Location: Bochum

Re: Need for guidance/clarification with the ArticyFlowPlaye

Fri 2. Aug 2019, 09:37

Hey Nico,

first of all: Hope you get paid enough for writing this wall of text :D

Thank you very much for those answers, I think I have a better understanding of the FlowPlayer now, highly appreciated!

One issue remains though, the "Ignore invalid Branches"-Flag (calling it IIB for now)

As mentioned in my example, if my condition in Articy looks like this:

Code: Select all
PlayerVariables.IsPlayerAlive == true;


And the IIB Flag is set to true and I don't set the condition to false in the Database the FlowPlayer executes as it should and my text gets updated.
When I set the condition to false in the DataBase and the IIB-Flag is still set to true the FlowPlayer stops before that node and does not traverse further.

In this case I expected the FlowPlayer to traverse through it, since it is ignoring invalid branches.
If this is by design I then wanted to know how to "brute force" through flow, meaning even if conditions need to be true or false at specific points I wanted to traverse through them for testing/debugging purposes. Or do I get the idea of ignoring invalid branches wrong? What is an invalid branch?
User avatar
btsslawa
 
Posts: 17
Joined: Fri 21. Aug 2015, 10:14

Re: Need for guidance/clarification with the ArticyFlowPlaye

Fri 2. Aug 2019, 13:03

Hi btsslawa,

first of all: Hope you get paid enough for writing this wall of text :D

Thank you very much for those answers, I think I have a better understanding of the FlowPlayer now, highly appreciated!


Its a pleasure talking and explaining what you yourself have created, especially if your opposite already put much effort into understanding it.
Im also always open to clarify any unclear issues and in doubt update the documentation for everyone else.

When I set the condition to false in the DataBase and the IIB-Flag is still set to true the FlowPlayer stops before that node and does not traverse further.

This is actually correct and i think its just a misunderstanding of the wording.

In the first case IIB does nothing, as your condition evaluates to true, and therefore its a valid branch.
When you change the variable to false, your branch evaluates to false, turning it into an invalid branch.
When the flow player now builds the AvailableBranches and IIB is set to true, all branches where IsValid is false (aka Invalid branches), are ignored and not part of the final available branches.
Calling now Play() does nothing, as we don't have any branches, because we are ignoring invalid ones. Play() without parameter, just follows the first branch found in AvailableBranches, or does nothing.

In other words: IIB means "Ignore all Invalid branches when showing me them" and not "Ignore if a branch is invalid when traversing".

Hope that clears it up :) let me know if you want to know anything else.

Best regards

Nico
Nico Probst
Senior Software Engineer | Articy | LinkedIn
User avatar
[Articy] Nico Probst
Articy Staff
Articy Staff
 
Posts: 217
Joined: Wed 23. Nov 2011, 09:45
Location: Bochum

Re: Need for guidance/clarification with the ArticyFlowPlaye

Fri 2. Aug 2019, 13:23

Ah, great, yeah, I did misunderstood the wording.
When IIB is set to false AND my condition is also set to false it "brute forces" through the nodes.

Thanks so much! :D
User avatar
btsslawa
 
Posts: 17
Joined: Fri 21. Aug 2015, 10:14

Return to articy:draft Unity Importer

Who is online

Users browsing this forum: No registered users and 6 guests

Who We Are
Contact Us
Social Links