Moving Documentation

wiki/docs/Multiuser.md

@@ -0,0 +1,105 @@
+# Multiuser
+
+More often than not when people make movies or any other project that requires an asset manager such as VCStudio, there is more than one person working. And usually more than one computer utilized. Sometimes the people behind the project are technically skilled to setup servers and synced directories. So the project will update automatically if either of the workers makes a change. But in some cases, those making the project use various non-productive practices, such as using USB sticks, or emailing the files over to the other worker. Which results in further need to re-organize the files manually. Making software like VCStudio kind of useless.
+
+This is why VCStudio has a special mode called Multiuser which allows two or more computers sitting on the same network to synchronize the project so all changes will be applied to all copies.
+
+### Chapters:
+
+ - [User Guide](#user-guide)
+ - [Protocol](#protocol)
+ - [Source Code](#source-code)
+
+# User Guide
+
+Before we gonna talk about how it works, I want you to be able to use it. This is one of those things that are so easy to use, you don't have to think much, but requires some understanding of the protocol in order to utilize it successfully and troubleshoot potential issues.
+
+In the [Story Editor](../../wiki/docs/Story-Editor.md) view, in the bottom, left corner you can find the ![](../../settings/themes/OldSchool/icons/multiuser.png) button. This gonna open an empty window with 3 sections. When the Multiuser is activated this window looks like this.
+
+![](https://notabug.org/jyamihud/update_manager/raw/master/vcstudio/64.png) 
+
+The top, left section is the server console. It also contains the ![](../../settings/themes/OldSchool/icons/server_new.png) button to activate or ![](../../settings/themes/OldSchool/icons/server_close.png) button to stop the Multiuser mode. To start the sync, you just have to press ![](../../settings/themes/OldSchool/icons/server_new.png) and forget about it. Technically this is all you need to do.
+
+Bottom, left is the list of currently connected users. If the other computer is on the same local network (connected to the same wifi) as this one. And the copy of the project is open via the VCStudio. It will connect automatically. 
+
+You can see that each user has a username. This username is set in the settings of the software. 
+
+![](https://notabug.org/jyamihud/update_manager/raw/master/vcstudio/66.png)
+
+You can see that this computer is set up to show a username of `J.Y.Amihud`. This is not registered in anyway. You don't need to apply for a username, or log into it using email and password. This username feature is there only for your convenience and implemented only locally. It's there to see who is connected. Who has what tasks, and who did what changes. Only your local network will know about the users of the Multiuser. 
+
+![](https://notabug.org/jyamihud/update_manager/raw/master/vcstudio/70.png)
+
+For example, in the scheduling window in [Analytics](../../wiki/docs/Analytics.md) you can setup various usernames to a specific task. Managing the workforce of the project.
+
+The same it true for the history. Every task recorded by the build in history protocol, also records the username. Meaning you can trace who done what and when. If you are a director or producer of the movie, you may not work on the animations and models. But you will be to make sure animators and modelers do their job properly using the Multiuser.
+
+Also when traveling the [Story Editor](../../wiki/docs/Story-Editor.md) while Multiuser is working. The two users can see each other as if it was some kind of multi-player game. 
+
+![](https://notabug.org/jyamihud/update_manager/raw/master/vcstudio/63.png)
+
+This image is running two instances of VCStudio on the same computer to illustrate how this going to look for the editors of the story.
+
+And let's not forget that on the right of the Multiuser window is a simple chat. Everybody can send a text message, to be received by all other connected users.
+
+# Protocol
+
+Now that you know how to activate and use the Multiuser, let's talk about how it actually works. 
+
+When your VCStudio is running, it's constantly listening to broadcast about a potential Multiuser. Such broadcasts can happen over a local network. Meaning if you have a router at home or in the studio. Even one that is not connected to the Internet. This Multiuser feature can be activate using this router. 
+
+When you click the ![](../../settings/themes/OldSchool/icons/server_new.png) button. It starts a small server on that machine. You can launch this program separately by doing a command `python3 run.py -ms`. The computer that is the Multiuser server doesn't even need to have the copy of the project on it. Just a working installation of VCStudio. 
+
+This server is going to broadcast via the router the IP and the name of the Project in plain text. So the users could catch this broadcast and connect to this server. 
+
+The server is the middle man. When ever you enter an asset or a scene. You send to the server that you have entered it, and the time in which the last edit of any of the files occurred in that asset or scene. The server will request the same information about this same asset or scene from all other users. And if you your computer has the most up to date version of this asset or scene, this asset or scene will be copied over to all the other computers. But if somebody else has a newer copy, you, and all the others will receive that copy.
+
+Instead of constantly checking the entire project for being up to date and constantly sending all files when ever somebody connects. The Multiuser is smart about it. But the approach of the Multiuser doesn't guarantee that all project's folders will be the same everywhere. Only the stuff you are accessing via the VCStudio will be updated.
+
+If you just simply launch VCStudio, to say, chat in the chat window. And open an asset that was updated elsewhere through the folder and not through the VCStudio. A request about whether it was updated will never be sent. So you will have the older version. Only when you access the asset from within the VCStudio the update will be requested in the first place and only then it will be updated.
+
+For more details let's look even closer and let's examine the Source Code of this synchronisation algorithm. 
+
+# Source Code
+
+The best documentation is to read the code of the software directly. For the multiuser I recommend:
+
+- [studio/studio_multiuserLayer.py](../../studio/studio_multiuserLayer.py) The UI of the Multiuser Window.
+- [network/insure.py](../../network/insure.py) A little socket based script that makes it easy to transfer complex objects over the network.
+- [network/multiuser_terminal.py](../../network/multiuser_terminal.py) The network part that reads the server outputs and send him primitive commands.
+- [network/network_multiuser.py](../../network/network_multiuser.py) The Client.
+- [network/multiuser_server.py](../../network/multiuser_server.py) The Server.
+
+**How does it connect?**
+
+When the server is started it broadcasts about it's IP on the local network's broadcast layer using UDP protocol. Which is on `255.255.255.255` IP adress. The users always listen to this broadcast on the background. If they see the name of the project in the broadcast message. They connect to the server using a more reliable TCP protocol.
+
+**How does it update the story?**
+
+Well the entire story is a large dictionary object that can be converted with ease to something like JSON. This is how the story is saved to the disk. And this is how it's transmitted over the network. It is done using [network/network_multiuser.py](../../network/network_multiuser.py).
+
+When the user connects, the server asks him to give the version of the story and the last modification time of the story file. If there is no story on the server or the user's story is newer then the one on the server. It will update and send the updated version to all the users.
+
+Same applies to the analytics. ( Schedules and History are parts of analytics ) All of those are also just large dictionaries easy to convert to JSON.
+
+**How does it update assets so quickly?**
+
+Well you don't need to copy over the entire thing. It would be silly. Every time a given user enters an asset or a shot. It will send to the server the last modification time of the folder. And the server will send this data to all the other users. 
+
+If some user has an older version. It will ask the server to get the new version for him. Of course this is not as straight forward because I wanted to optimize this even further. The first user will send the full list of files and folders in a requested folder with MD5 hashes for each. The second user will compare the hashes. And only when the hash is changed. Only then the file is transferred. Change of the hash means that something in the file is changed. If the hashes are identical it means that the files are identical, and therefor this files do not need updating.
+
+**How do I see where other users are in the story editor?**
+
+When the story is transferred. It carries over the `camera` variable. Which is the location of the user in the story editor space. I can take this data and update the user's list with it. The one who has the latest story will be updated with the latest camera. And then I draw a little icon and a name to that location.
+
+
+# Help The Documentation
+
+The documentation files are not perfect. And need maintenance.
+
+*If you are reading it from the VCStudio build in Documentation:*
+
+ - Press ![](../../settings/themes/OldSchool/icons/edit.png) to edit locally.
+ - Press ![](../../settings/themes/OldSchool/icons/notabug.png) to commit in our NotABug repository.
+
+*(C) J.Y.Amihud 2021. Under GPL v3 or later.*