Backups/multi-user
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add cloud hosting instructions, updated Dockerfile

Browse Source
This commit is contained in:
brybalicious
2020-11-24 23:00:44 +01:00
parent 46414aef13
commit ed0c5d9431
31 changed files with 536 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
docs/getting_started/quickstart.rst
View File

@ -5,10 +5,10 @@ Quick start
===========
.. hint::
*All session related settings are located under: `View3D -> Sidebar -> Multiuser panel`*
*All session-related settings are located under: `View3D -> Sidebar -> Multiuser panel`*
The multi-user is based on a session management system.
In this this guide you will quickly learn how to use the collaborative session system in three part:
The multi-user addon provides a session management system.
In this guide, you will quickly learn how to use the collaborative session management system in three parts:
- :ref:`how-to-host`
- :ref:`how-to-join`
@ -19,22 +19,22 @@ In this this guide you will quickly learn how to use the collaborative session s
How to host a session
=====================
The multi-user add-on rely on a Client-Server architecture.
The server is the heart of the collaborative session,
it will allow each users to communicate with each others.
The multi-user add-on relies on a Client-Server architecture.
The server is the heart of the collaborative session.
It is what allows user's blender instances to communicate with each other.
In simple terms, *Hosting a session* means *run a local server and connect the local client to it*.
When I said **local server** I mean accessible from the LAN (Local Area Network).
When I say **local server** I mean a server which is accessible from the LAN (Local Area Network) without requiring an internet connection.
However sometime you will need to host a session over the internet,
in this case I strongly recommand you to read the :ref:`internet-guide` tutorial.
However, there are times when you will need to host a session over the internet.
In this case, I strongly recommend that you read the :ref:`internet-guide` tutorial.
.. _user-info:
-----------------------------
1. Fill your user information
-----------------------------
--------------------------------
1. Fill in your user information
--------------------------------
The **User Info** panel (See image below) allow you to constomize your online identity.
The **User Info** panel (See image below) allows you to customise your online identity.
.. figure:: img/quickstart_user_info.png
:align: center
@ -42,38 +42,38 @@ The **User Info** panel (See image below) allow you to constomize your online id
User info panel
Let's fill those tow field:
Let's fill those two fields:
- **name**: your online name.
- **color**: a color used to represent you into other user workspace(see image below).
- **color**: a color used to represent you in other user's workspaces(see image below).
During online sessions, other users will see your selected object and camera hilghlited in your profile color.
During online sessions, other users will see your selected object and camera highlighted in your profile color.
.. _user-representation:
.. figure:: img/quickstart_user_representation.png
:align: center
User viewport representation
User viewport representation aka 'User Presence'
--------------------
2. Setup the network
--------------------
---------------------
2. Set up the network
---------------------
When the hosting process will start, the multi-user addon will lauch a local server instance.
In the nerwork panel select **HOST**.
The **Host sub-panel** (see image below) allow you to configure the server according to:
When the hosting process starts, the multi-user addon will launch a local server instance.
In the network panel, select **HOST**.
The **Host sub-panel** (see image below) allows you to configure the server according to:
* **Port**: Port on wich the server is listening.
* **Port**: Port on which the server is listening.
* **Start from**: The session initialisation method.
* **current scenes**: Start with the current blendfile datas.
* **an empty scene**: Clear a data and start over.
* **current scenes**: Start with the data loaded in the current blend file.
* **an empty scene**: Clear the blend file's data and start over.
.. danger::
By starting from an empty, all of the blend data will be removed !
Ensure to save your existing work before launching the session.
By starting from an empty scene, all of the blend data will be removed!
Be sure to save your existing work before launching the session.
* **Admin password**: The session administration password.
@ -84,16 +84,16 @@ The **Host sub-panel** (see image below) allow you to configure the server accor
Host network panel
.. note:: Additionnal configuration setting can be found in the :ref:`advanced` section.
.. note:: Additional configuration setting can be found in the :ref:`advanced` section.
Once everything is setup you can hit the **HOST** button to launch the session !
Once everything is set up, you can hit the **HOST** button to launch the session!
It will do two things:
This will do two things:
* Start a local server
* Connect you to it as an :ref:`admin`
During online session, various actions are available to you, go to :ref:`how-to-manage` section to
During an online session, various actions are available to you, go to :ref:`how-to-manage` section to
learn more about them.
.. _how-to-join:
@ -101,12 +101,12 @@ learn more about them.
How to join a session
=====================
This section describe how join a launched session.
Before starting make sure that you have access to the session ip and port.
This section describes how join a launched session.
Before starting make sure that you have access to the session IP address and port number.
-----------------------------
1. Fill your user information
-----------------------------
--------------------------------
1. Fill in your user information
--------------------------------
Follow the user-info_ section for this step.
@ -114,9 +114,9 @@ Follow the user-info_ section for this step.
2. Network setup
----------------
In the nerwork panel select **JOIN**.
The **join sub-panel** (see image below) allow you configure the client to join a
collaborative session.
In the network panel, select **JOIN**.
The **join sub-panel** (see image below) allows you to configure your client to join a
collaborative session which is already hosted.
.. figure:: img/quickstart_join.png
:align: center
@ -124,32 +124,32 @@ collaborative session.
Connection panel
Fill those field with your information:
Fill in the fields with your information:
- **IP**: the host ip.
- **Port**: the host port.
- **Connect as admin**: connect you with **admin rights** (see :ref:`admin` ) to the session.
- **IP**: the host's IP address.
- **Port**: the host's port number.
- **Connect as admin**: connect yourself with **admin rights** (see :ref:`admin` ) to the session.
.. Maybe something more explicit here
.. note::
Additionnal configuration setting can be found in the :ref:`advanced` section.
Additional configuration settings can be found in the :ref:`advanced` section.
Once you've set every field, hit the button **CONNECT** to join the session !
When the :ref:`session-status` is **ONLINE** you are online and ready to start to collaborate.
Once you've configured every field, hit the button **CONNECT** to join the session !
When the :ref:`session-status` is **ONLINE** you are online and ready to start co-creating.
.. note::
On the **dedicated server** startup, the session status will get you to the **LOBBY** waiting a admin to start it.
When starting a **dedicated server**, the session status screen will take you to the **LOBBY**, awaiting an admin to start the session.
If the session status is set to **LOBBY** and you are a regular user, you need to wait that an admin launch it.
If you are the admin, you just need to init the repository to start the session (see image below).
If the session status is set to **LOBBY** and you are a regular user, you need to wait for the admin to launch the scene.
If you are the admin, you just need to initialise the repository to start the session (see image below).
.. figure:: img/quickstart_session_init.png
:align: center
Session initialisation for dedicated server
During online session, various actions are available to you, go to :ref:`how-to-manage` section to
During an online session, various actions are available to you. Go to :ref:`how-to-manage` to
learn more about them.
.. _how-to-manage:
@ -157,17 +157,17 @@ learn more about them.
How to manage a session
=======================
The collaboration quality directly depend on the communication quality. This section describes
various tools made in an effort to ease the communication between the different session users.
Feel free to suggest any idea for communication tools `here <https://gitlab.com/slumber/multi-user/-/issues/75>`_ .
The quality of a collaborative session directly depends on the quality of the network connection, and the communication between the users. This section describes
various tools which have been made in an effort to ease the communication between your fellow creators.
Feel free to suggest any ideas for communication tools `here <https://gitlab.com/slumber/multi-user/-/issues/75>`_ .
---------------------------
Change replication behavior
---------------------------
During a session, the multi-user will replicate your modifications to other instances.
In order to avoid annoying other users when you are experimenting, some of those modifications can be ignored via
various flags present at the top of the panel (see red area in the image bellow). Those flags are explained in the :ref:`replication` section.
During a session, multi-user will replicate all of your local modifications to the scene, to all other users' blender instances.
In order to avoid annoying other users when you are experimenting, you can flag some of your local modifications to be ignored via
various flags present at the top of the panel (see red area in the image below). Those flags are explained in the :ref:`replication` section.
.. figure:: img/quickstart_replication.png
:align: center
@ -178,32 +178,31 @@ various flags present at the top of the panel (see red area in the image bellow)
Monitor online users
--------------------
One of the most vital tool is the **Online user panel**. It list all connected
users information's including yours such as :
One of the most vital tools is the **Online user panel**. It lists all connected
users' information including your own:
* **Role** : if user is an admin or a regular user.
* **Role** : if a user is an admin or a regular user.
* **Location**: Where the user is actually working.
* **Frame**: When (in frame) the user working.
* **Ping**: user connection delay in milliseconds
* **Frame**: When (on which frame) the user is working.
* **Ping**: user's connection delay in milliseconds
.. figure:: img/quickstart_users.png
:align: center
Online user panel
By selecting a user in the list you'll have access to different user related **actions**.
Those operators allow you reach the selected user state in tow different dimensions: **SPACE** and **TIME**.
By selecting a user in the list you'll have access to different users' related **actions**.
Those operators allow you to experience the selected user's state in two different dimensions: **SPACE** and **TIME**.
Snapping in space
----------------
-----------------
The **CAMERA button** (Also called **snap view** operator) allow you to snap on
the user viewpoint. To disable the snap, click back on the button. This action
served different purposes such as easing the review process, working together on
wide world.
The **CAMERA button** (Also called **snap view** operator) allow you to snap to
the user's viewpoint. To disable the snap, click on the button once again. This action
serves different purposes such as easing the review process, and working together on a large or populated world.
.. hint::
If the target user is localized on another scene, the **snap view** operator will send you to his scene.
If the target user is located in another scene, the **snap view** operator will send you to their scene.
.. figure:: img/quickstart_snap_view.gif
:align: center
@ -211,11 +210,11 @@ wide world.
Snap view in action
Snapping in time
---------------
----------------
The **CLOCK button** (Also called **snap time** operator) allow you to snap on
the user time (current frame). To disable the snap, click back on the button.
This action is built to help various actors to work on the same temporality
The **CLOCK button** (Also called **snap time** operator) allows you to snap to
the user's time (current frame). To disable the snap, click on the button once again.
This action helps various multiple creators to work in the same time-frame
(for instance multiple animators).
.. figure:: img/quickstart_snap_time.gif
@ -230,14 +229,14 @@ Kick a user
.. warning:: Only available for :ref:`admin` !
The **CROSS button** (Also called **kick** operator) allow the admin to kick the selected user. On the target user side, the session will properly disconnect.
The **CROSS button** (Also called **kick** operator) allows the administrator to kick the selected user. This can be helpful if a user is acting unruly, but more importantly, if they are experiencing a high ping which is slowing down the scene. Meanwhile, in the target user's world, the session will properly disconnect.
Change users display
--------------------
Presence is the multi-user module responsible for users display. During the session,
it draw users related information in your viewport such as:
Presence is the multi-user module responsible for displaying user presence. During the session,
it draw users' related information in your viewport such as:
* Username
* User point of view
@ -248,10 +247,10 @@ it draw users related information in your viewport such as:
Presence show flags
The presence overlay panel (see image above) allow you to enable/disable
The presence overlay panel (see image above) allows you to enable/disable
various drawn parts via the following flags:
- **Show session statut**: display the session status in the viewport
- **Show session status**: display the session status in the viewport
.. figure:: img/quickstart_status.png
:align: center
@ -259,8 +258,8 @@ various drawn parts via the following flags:
- **Text scale**: session status text size
- **Vertical/Horizontal position**: session position in the viewport
- **Show selected objects**: display other users current selection
- **Show users**: display users current viewpoint
- **Show selected objects**: display other users' current selections
- **Show users**: display users' current viewpoint
- **Show different scenes**: display users working on other scenes
@ -269,40 +268,40 @@ various drawn parts via the following flags:
Manage data
-----------
In order to understand replication data managment, a quick introduction to the multi-user data workflow is required.
First thing to know: until now, the addon rely on a data-based replication. In simple words, it means that it replicate
user's action results.
To replicate datablocks between clients the multi-user rely on what tends to be a distributed architecture:
In order to understand replication data managment, a quick introduction to the multi-user data workflow is in order.
The first thing to know: until now, the addon relies on data-based replication. In simple words, it means that it replicates
the resultant output of a user's actions.
To replicate datablocks between clients, multi-user relies on a standard distributed architecture:
- The server store the "master" version of the work.
- Each client have a local version of the work.
- The server stores the "master" version of the work.
- Each client has a local version of the work.
When an artist modified something in the scene, here is what is happening in the background:
When an artist modifies something in the scene, here is what is happening in the background:
1. Modified data are **COMMITTED** to the local repository.
2. Once committed locally, they are **PUSHED** to the server
3. As soon as the server is getting updates, they are stored locally and pushed to every other clients
3. As soon as the server receives updates, they are stored locally and pushed to every other client
At the top of this data management system, a right management system prevent
multiple users from modifying same data at same time. A datablock may belong to
At the top of this data management system, a rights management system prevents
multiple users from modifying the same data at the same time. A datablock may belong to
a connected user or be under :ref:`common-right<**COMMON**>` rights.
.. note::
In a near future, the right management system will support roles to allow multiple users to
work on different aspect of the same datablock.
In a near future, the rights management system will support roles to allow multiple users to
work on different aspects of the same datablock.
The Repository panel (see image below) allow you to monitor, change datablock states and right manually.
The Repository panel (see image below) allows you to monitor, change datablock states and rights manually.
.. figure:: img/quickstart_properties.png
:align: center
Repository panel
The **show only owned** flag allow you to see which datablocks you are currently modifying.
The **show only owned** flag allows you to see which datablocks you are currently modifying.
.. warning::
If you are editing a datablock not listed with this fag enabled, it means that you do
not have right granted to modify it. So it won't be updated to other client !
If you are editing a datablock not listed with this flag enabled, it means that you have not been granted the rights to modify it.
So, it won't be updated to other clients!
Here is a quick list of available actions:
@ -342,12 +341,12 @@ Network
Advanced network settings
**IPC Port** is the port used for Inter Process Communication. This port is used
by the multi-users subprocesses to communicate with each others. If different instances
of the multi-user are using the same IPC port it will create conflict !
by the multi-user subprocesses to communicate with each other. If different instances
of multi-user are using the same IPC port, this will create conflict !
.. note::
You only need to modify it if you need to launch multiple clients from the same
computer(or if you try to host and join on the same computer). You should just enter a different
You only need to modify this setting if you need to launch multiple clients from the same
computer (or if you try to host and join from the same computer). To resolve this, you simply need to enter a different
**IPC port** for each blender instance.
**Timeout (in milliseconds)** is the maximum ping authorized before auto-disconnecting.
@ -364,20 +363,20 @@ Replication
Advanced replication settings
**Synchronize render settings** (only host) enable replication of EEVEE and CYCLES render settings to match render between clients.
**Synchronize render settings** (only host) enable replication of EEVEE and CYCLES render settings to match renders between clients.
**Synchronize active camera** sync the scene active camera.
**Synchronize active camera** sync the scene's active camera.
**Edit Mode Updates** enable objects update while you are in Edit_Mode.
**Edit Mode Updates** enable objects to update while you are in Edit_Mode.
.. warning:: Edit Mode Updates kill performances with complex objects (heavy meshes, gpencil, etc...).
.. warning:: Edit Mode Updates kills the session's performance with complex objects (heavy meshes, gpencil, etc...).
**Update method** allow you to change how replication update are triggered. Until now two update methode are implemented:
**Update method** allows you to change how replication updates are triggered. Until now, two update methods are implemented:
- **Default**: Use external threads to monitor datablocks changes, slower and less accurate.
- **Default**: Use external threads to monitor datablocks changes. Slower and less accurate.
- **Despgraph ⚠️**: Use the blender dependency graph to trigger updates. Faster but experimental and unstable !
**Properties frequency gird** allow to set a custom replication frequency for each type of data-block:
**Properties frequency grid** set a custom replication frequency for each type of data-block:
- **Refresh**: pushed data update rate (in second)
- **Apply**: pulled data update rate (in second)
@ -386,21 +385,21 @@ Replication
Cache
-----
The multi-user allows to replicate external blend dependencies such as images, movies sounds.
On each client, those files are stored into the cache folder.
Multi-user allows you to replicate external dependencies such as images (textures, hdris, etc...), movies, and sounds.
On each client, the files will be stored in the multi-user cache folder.
.. figure:: img/quickstart_advanced_cache.png
:align: center
Advanced cache settings
**cache_directory** allows to choose where cached files (images, sound, movies) will be saved.
**cache_directory** choose where cached files (images, sound, movies) will be saved.
**Clear memory filecache** will save memory space at runtime by removing the file content from memory as soon as it have been written to the disk.
**Clear memory filecache** will save memory space at runtime by removing the file content from memory as soon as it has been written to the disk.
**Clear cache** will remove all file from the cache folder.
**Clear cache** will remove all files from the cache folder.
.. warning:: Clear cash could break your scene image/movie/sound if they are used into the blend !
.. warning:: Clearing the cache could break your scene images/movies/sounds if they are used in a blend file! Try saving the blend file and choosing 'Pack all into blend' before clearing the cache.
---
Log
@ -411,16 +410,16 @@ Log
Advanced log settings
**log level** allow to set the logging level of detail. Here is the detail for each values:
**log level** allows you to set the level of detail captured in multi-user's logging output. Here is a brief description on the level of detail for each value of the logging parameter:
+-----------+-----------------------------------------------+
| Log level | Description |
+===========+===============================================+
| ERROR | Shows only critical error |
| ERROR | Shows only critical errors |
+-----------+-----------------------------------------------+
| WARNING | Shows only errors (all kind) |
| WARNING | Shows only errors (of all kinds) |
+-----------+-----------------------------------------------+
| INFO | Shows only status related messages and errors |
| INFO | Shows only status-related messages and errors |
+-----------+-----------------------------------------------+
| DEBUG | Shows every possible information. |
| DEBUG | Shows all possible information |
+-----------+-----------------------------------------------+