Commit bc47ef95 authored by Fabian Adam's avatar Fabian Adam
Browse files

feat: getting started

parent de7417f0
Pipeline #362343762 failed
\ No newline at end of file
Key Features
Session management
Easier communication
Sync Datablocks
\ No newline at end of file
About Multi-User
.. toctree::
:maxdepth: 1
:name: toc-about
:maxdepth: 2
About Multi-user
The idea
......@@ -14,9 +11,4 @@ A film is an idea carved along the whole production process by many different pe
Nowadays it's a known fact that real-time rendering technologies allows to speedup traditional linear production by reducing drastically the iteration time across different steps. All majors industrial CG solutions are moving toward real-time horizons to bring innovative interactive workflows. But this is a microscopic, per-task/solution vision of real-time rendering benefits for the animation production. What if we step-back, get a macroscopic picture of an animation movie pipeline and ask ourself how real-time could change our global workflow ? Could-it bring better ways of working together by giving more visibility between departments during the whole production ?
The multi-user addon is an attempt to experiment real-time parallelism between different production stage. By replicating blender data blocks over the networks, it allows different artists to collaborate on a same scene in real-time.
Others ?
What it is/Key Features/Creator/Community
\ No newline at end of file
The multi-user addon is an attempt to experiment real-time parallelism between different production stage. By replicating blender data blocks over the networks, it allows different artists to collaborate on a same scene in real-time.
\ No newline at end of file
......@@ -14,4 +14,105 @@ Side Pannel
\ No newline at end of file
Advanced settings
This section contains optional settings to configure the session behavior.
.. figure:: img/quickstart_advanced.png
:align: center
Advanced configuration panel
.. figure:: img/quickstart_advanced_network.png
:align: center
Advanced network settings
**Timeout (in milliseconds)** is the maximum ping authorized before auto-disconnecting.
You should only increase it if you have a bad connection.
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** 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 has been written to the disk.
**Clear cache** will remove all files from the cache folder.
.. 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.
.. figure:: img/quickstart_advanced_logging.png
:align: center
Advanced log settings
**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 errors |
| WARNING | Shows only errors (of all kinds) |
| INFO | Shows only status-related messages and errors |
| DEBUG | Shows all possible information |
Save session data
.. danger::
This is an experimental feature, until the stable release it is highly recommended to use regular .blend save.
The save session data allows you to create a backup of the session data.
When you hit the **save session data** button, the following popup dialog will appear.
It allows you to choose the destination folder and if you want to run an auto-save.
.. figure:: img/quickstart_save_session_data_dialog.png
:align: center
Save session data dialog.
If you enabled the auto-save option, you can cancel it from the **Cancel auto-save** button.
.. figure:: img/quickstart_save_session_data_cancel.png
:align: center
Cancel session autosave.
To import session data backups, use the following **Multiuser session snapshot** import dialog
.. figure:: img/quickstart_import_session_data.png
:align: center
Import session data dialog.
.. note::
It is not yet possible to start a session directly from a backup.
.. _advanced:
......@@ -16,7 +16,7 @@ import sys
# -- Project information -----------------------------------------------------
project = 'multi-user'
project = 'Multi-User 0.5.0 Documentation'
copyright = '2020, Swann Martinez'
author = 'Swann Martinez, Poochy, Fabian'
......@@ -100,16 +100,14 @@ if html_theme == "sphinx_rtd_theme":
# "<project> v<release> documentation" by default.
html_title = "Multi-User Doc"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = "resources/theme/multi-user-logo.svg"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_logo = "resources/logo.png"
html_favicon = "ressources/favicon.ico"
html_static_path = ["resources"]
if html_theme == "sphinx_rtd_theme":
html_css_files = ["css/theme_overrides.css"]
.. _firstlaunch:
First launch
Welcome to the Multi-User manual.
You will find here all the documentation necessary for the good use of the addon: :ref:`index-manual`
First of all, let's have a quick look at the Multi-User features.
Username and color
When you launch the addon for the first time you can find this panel in the Sidebar of your View3D:
.. figure:: img/first_time_menu.png
:align: center
1. Choose a **name** and a **color** that will be specific to you and that will allow others to identify you easily once in session. Don't worry, they can be changed at any time in *Edit >> Prerecences >> Add-ons >> Multi-user* or in *Multi-User Pannel >> General Settings*
2. Press **Continue**
Multi-User side pannel
Once the Multi-User is launched you will arrive directly on the main menu:
.. figure:: img/first_time_server_list.png
:align: center
Three panels are at your disposal:
- **Server list**: You can add, delete and edit server presets according to your preferences. At first launch two servers will already be in your preferences: *Public Session*, the public server of the Multi-User Discord, *Localhost*, to connect locally to your server.
- **Hosting**: To locally host a session with a Blender instance.
- **Advanced Settings**: Include advanced addon settings like *user info*, *server ping*, *cache*, etc.
See :ref:`quickstart` to continue
\ No newline at end of file
.. glossary::
.. _admin:
*A session administrator can manage users (kick) and hold write access on
each datablock. They can also init a dedicated server repository.*
.. _session-status:
session status
*Located in the title of the multi-user panel, the session status shows
you the connection state.*
.. figure:: img/quickstart_session_status.png
:align: center
Session status in panel title bar
All possible connection states are listed here with their meaning:*
| State | Description |
| WARMING UP DATA | Commiting local data |
| FETCHING | Dowloading snapshot from the server |
| AUTHENTICATION | Initial server authentication |
| ONLINE | Connected to the session |
| PUSHING | Init the server repository by pushing ours |
| INIT | Initial state |
| QUITTING | Exiting the session |
| LAUNCHING SERVICES | Launching local services. Services are spetialized daemons running in the background. ) |
| LOBBY | The lobby is a waiting state triggered when the server repository hasn't been initiated yet |
| | |
| | Once initialized, the server will automatically launch all client in the **LOBBY**. |
.. _common-right:
common right
When a data block is under common right, it is available to everyone for modification.
The rights will be given to the user that selects it first.
\ No newline at end of file
.. _how-to-host:
How to host a session
Local server
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 we say **local server** we mean a server which is accessible from the LAN (Local Area Network) without requiring an internet connection.
.. _local-setup:
When the hosting process starts, the multi-user addon will launch a local server instance.
In the **Hosting** panel configure your server according to:
.. figure:: img/first_time_server_host.png
:align: center
Hosting panel
* **Init the session from**: the session initialisation method.
* **current scenes**: start with the data loaded in the current blend file.
* **an empty scene**: clear the blend file's data and start over.
* **Port**: port on which the server is listening.
* **Server password**: (*optional*) the server password.
* **Admin password**: (*optional*) the session administration password.
Once everything is set up, you can hit the **Host** button to launch the session!
This will do two things:
* Start a local server
* Connect you to it as an :ref:`admin`
.. danger::
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.
Online server
However, there are times when you will need to host a session over the internet.
In this case, we strongly recommend that you read the :ref:`internet-guide` tutorial.
During an online session, various actions are available to you, go to :ref:`how-to-manage` section to
learn more about them.
\ No newline at end of file
.. _how-to-join:
How to join a session
This section describes how to join a launched session.
Before starting make sure that you have access to the session **IP address**, **port number** and that you have filled in your **user information** (name and color).
Server List
The server list allows you to manage your servers:
.. figure:: img/quickstart_serverlist.png
:align: center
:width: 200px
Server List
To connect to a server, select the one you want to join in the list and click on **Connect**.
To know if the server you want to join is online, you can refresh your server list with the button on the top right corner.
Online status:
- **Red**: server is offline
- **Green**: server is online
.. note::
If a server is secured with a password, a lock will be displayed next to the server name. You first need to enter the password of the server in its preset to join it.
.. figure:: img/quickstart_serverlist_private.png
:align: center
:width: 200px
It is possible to **add**, **delete** and even **modify** a **server preset** with the buttons located on the top right of the server list:
.. figure:: img/quickstart_serverlist_manage_buttons.png
:align: center
:width: 200px
Add, Remove, Edit Server Preset
.. note::
Two server presets are already present when the addon is launched:
- The 'localhost' preset, to join a local session quickly
- The 'public session' preset, to join the public sessions of the multi-user server (official discord to participate :
Add a Server Preset
To add a server, you must first register it in the server list. Click on the **+** icon and fill in the window with the server settings:
.. figure:: img/quickstart_server_edit.png
:align: center
:width: 350px
Server Preset pop-up
- **Server name**: the name of the server.
- **IP**: the host's IP address.
- **Port**: the host's port number.
- **Server password**: (*optional*) the server password.
- **Admin password**: (*optional*) the session administration password.
Once you've configured every field, you can save the server preset by clicking **OK**.
You can now select it in the server list to join the session !
.. warning:: Be careful, if you don't rename your new preset, or if it has the same name as an existing preset, the old preset will be overwritten.
.. figure:: img/server_preset_image_report.png
:align: center
:width: 200px
Joining a server
When joining a server that have already be initialise, the session status screen will be **CONNECT**.
You are now connected and can start creating.
.. figure:: img/quickstart_connect.png
:align: center
In session
During an online session, various actions are available to you. Go to :ref:`how-to-manage` to
learn more about them.
When starting a **dedicated server**, the session status screen will take you to the **LOBBY** (see side-panel header).
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 (admins have shield next to their names).
If you are the admin, you just need to initialise the session to start it (see image below).
.. figure:: img/quickstart_lobby.png
:align: center
Session initialisation for dedicated server
\ No newline at end of file
.. _how-to-manage:
How to manage a session
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 <>`_ .
Monitor online users
One of the most vital tools is the **Online user panel**. It lists all connected
users' information including your own:
* **Role** : admin/regular user.
* **Username** : name of the user.
* **Mode** : user's active mode (object, sculpt, paint,etc.).
* **Frame**: on which frame the user is working.
* **Location**: where the user is actually 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 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 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 located in another scene, the **snap view** operator will send you to their scene.
.. figure:: img/quickstart_snap_camera.gif
:align: center
Snap view in action
Snapping in time
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
:align: center
Snap time in action
Kick a user
.. warning:: Only available for :ref:`admin` !
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 replication behavior
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_synchronize.png
:align: center
Session replication flags
Manage data
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 stores the "master" version of the work.
- Each client has a local version of the work.
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 receives updates, they are stored locally and pushed to every other client
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 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) allows you to monitor, change datablock states and rights manually.
.. figure:: img/quickstart_repository.png
:align: center
Repository panel
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 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:
| icon | Action | Description |
| .. image:: img/quickstart_push.png | **Push** | push data-block to other clients |
| .. image:: img/quickstart_pull.png | **Pull** | pull last version into blender |
| .. image:: img/quickstart_refresh.png | **Reset** | Reset local change to the server version |
| .. image:: img/quickstart_unlock.png | **Lock/Unlock** | If locked, does nothing. If unlocked, grant modification rights to another user. |
| .. image:: img/quickstart_remove.png | **Delete** | Remove the data-block from network replication |
\ No newline at end of file
This image diff could not be displayed because it is too large. You can view the blob instead.
......@@ -7,7 +7,9 @@ Getting started