Merge branch 'develop' into 'master'

v0.5.0

See merge request slumber/multi-user!164

CHANGELOG.md

@@ -217,3 +217,26 @@ All notable changes to this project will be documented in this file.
 - GPencil fill stroke
 - Sculpt and GPencil brushes deleted when joining a session (@Kysios)
 - Auto-updater doesn't work for master and develop builds
+
+## [0.5.0] - 2022-02-10
+
+### Added
+
+- New overall UI and UX (@Kysios)
+- Documentation overall update (@Kysios)
+- Server presets (@Kysios)
+- Server online status (@Kysios)
+- Draw connected user color in the user list
+- Private session (access protected with a password) (@Kysios)
+
+### Changed
+
+- Dependencies are now installed in the addon folder and correctly cleaned during the addon removal process
+
+### Fixed
+
+- Python 3.10 compatibility (@notfood)
+- Blender 3.x compatibility
+- Skin vertex radius synchronization (@kromar)
+- Sequencer audio strip synchronization
+- Crash with empty after a reconnection

docs/about/community.rst

@@ -0,0 +1,17 @@
+=========
+Community
+=========
+
+Discord
+=======
+
+Feel free to join our `discord server <https://discord.gg/aBPvGws>`_ ! 
+
+You will find help, a way to take part in the project, public collaborative sessions, people to create with, information about the addon's progress and much more.
+
+.. TODO: Make a call on discord get a link / image for evry contributor ?
+
+Contributors
+============
+
+Swann, Fabian, NotFood, Poochyc, Valentin, Adrien, Tanguy, Bruno, Gorgio, Axel, Ultr-X, Wuaieyo, Softyoda, Staz, Ikxi, Kysios.

docs/about/features.rst

@@ -0,0 +1,32 @@
+============
+Key Features
+============
+
+Multi-User is a free and open source blender addon. 
+It aims to allow multiple users to work on the same scene over the network. Based on a Clients / Server architecture, the data-oriented replication schema replicate blender data-blocks across the wire.
+
+.. warning::
+    The addon is still in development Be carefull when using it. 
+
+    On rare occasions, it can happen that your blender scenes become corrupted, think of making backups to avoid losing your projects. 
+
+Collaboration
+=============
+
+Multi-User allows a strong collaborative workflow between users. Being able to collaborate in this way has opened up new opportunities:
+
+
+- Being able to create together and in real time on the same 3D scene, with instant feedback.
+- Being able to teach directly in the same 3D environment in real time, facilitating communication between the teacher and these students.
+- To be able to experiment with several people, to make challenges or simply to have fun.
+- And much more !
+
+Easier communication
+====================
+
+Thanks to *presence*, the overlay system that Multi-User provides, it is possible to see other users in the 3D space. The *presence* overlay is customizable to match your preferences (visibility, names, options).
+
+Session management
+==================
+
+The addon works on a session system. The creator of the session and the administrators have rights that allow them to easily manage the session (backups, user management). In addition, there is a management of datablock rights so that each user can collaborate as they wish.

docs/about/index.rst

@@ -1,8 +1,10 @@
-About
-=====
+================
+About Multi-User
+================
 
 .. toctree::
-   :maxdepth: 1
-   :name: toc-about
+   :maxdepth: 2
 
    introduction
+   features
+   community

docs/about/introduction.rst

@@ -1,7 +1,6 @@
-============
-Introduction
-============
-
+========
+The idea
+========
 
 A film is an idea carved along the whole production process by many different peoples. A traditional animation pipeline involve a linear succession of tasks. From storyboard to compositing by passing upon different step, its fundamental work flow is similar to an industrial assembly line. Since each step is almost a department, its common that one person on department B doesn't know what another person did on a previous step in a department A. This lack of visibility/communication could be a source of problems which could produce a bad impact on the final production result.
 
@@ -12,4 +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.
+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.

docs/conf.py

@@ -12,17 +12,16 @@
 #
 import os
 import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'multi-user'
+project = 'Multi-User 0.5.0 Documentation'
 copyright = '2020, Swann Martinez'
 author = 'Swann Martinez, Poochy, Fabian'
 
 # The full version, including alpha/beta/rc tags
-release = '0.5.0-develop'
+version_release = '0.5.1-develop'
 
 
 # -- General configuration ---------------------------------------------------
@@ -42,12 +41,15 @@ source_suffix = ".rst"
 # The master toctree document.
 master_doc = "index"
 
+# General information about the projet
+projet = 'Multi-User %s Doc' % version_release
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#
+
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'python'
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -60,28 +62,59 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-import sphinx_rtd_theme
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "default"
+
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    del sphinx_rtd_theme
+except ModuleNotFoundError:
+    pass
+
 if on_rtd:
     using_rtd_theme = True
 
-# Theme options
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
 html_theme_options = {
-    # 'typekit_id': 'hiw1hhg',
-    # 'analytics_id': '',
-    # 'sticky_navigation': True  # Set to False to disable the sticky nav while scrolling.
-    # 'logo_only': True,  # if we have a html_logo below, this shows /only/ the logo with no title text
     'collapse_navigation': False,  # Collapse navigation (False makes it tree-like)
-    # 'display_version': True,  # Display the docs version
-    # 'navigation_depth': 4,  # Depth of the headers shown in the navigation bar
 }
 
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = []
+
+if html_theme == "sphinx_rtd_theme":
+    html_theme_options = {
+        "analytics_id": "UA-1418081-1",
+        # included in the title
+        "display_version": False,
+        "collapse_navigation": True,
+        "navigation_depth": -1,
+    }
+
+    extensions.append('sphinx_rtd_theme')
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+html_title = "Multi-User Doc"
+
+# 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"]
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'multiusrdoc'
+htmlhelp_basename = 'Multi-User Manual'
 
 # sphinx-notfound-page
 # https://github.com/readthedocs/sphinx-notfound-page

docs/general_settings/index.rst

@@ -0,0 +1,117 @@
+################
+General Settings
+################
+
+This section contains optional settings to configure before a session.
+
+.. figure:: img/sidepannel_general_settings.png
+   :align: center
+   
+   General Settings pannel
+
+---------
+User info
+---------
+
+.. figure:: img/sidepannel_userinfo.png
+   :align: center
+
+   User Info settings
+
+The **User Info** pannel is here to change your user name and use color.
+
+-------
+Network
+-------
+
+.. figure:: img/sidepannel_network.png
+   :align: center
+
+   Network settings
+
+**Timeout (in milliseconds)** is the maximum ping authorized before auto-disconnecting.
+You should only increase it if you have a bad connection.
+
+-----
+Cache
+-----
+
+.. figure:: img/sidepannel_cache.png
+   :align: center
+
+   Cache settings
+
+
+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.
+
+
+
+**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.
+
+-------
+Logging
+-------
+
+.. figure:: img/sidepannel_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, it is still 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:

docs/getting_started/glossary.rst

@@ -1,59 +0,0 @@
-========
-Glossary
-========
-
-
-.. glossary::
-
-   .. _admin:
-   
-   administrator
-
-      *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. 

docs/getting_started/how-to-host.rst

@@ -0,0 +1,54 @@
+.. _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:`hosting_on_internet` tutorial.
+
+During an online session, various actions are available to you, go to :ref:`how-to-manage` section to 
+learn more about them.

docs/getting_started/how-to-join.rst

@@ -0,0 +1,104 @@
+.. _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 : https://discord.gg/aBPvGws)
+
+-------------------
+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.
+
+----------------
+Joining a server
+----------------
+
+CONNECT
+-------
+
+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.
+
+LOBBY
+-----
+
+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

docs/getting_started/how-to-manage.rst

@@ -0,0 +1,135 @@
+.. _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 <https://gitlab.com/slumber/multi-user/-/issues/75>`_ .
+
+--------------------
+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                                     |
++---------------------------------------+-------------------+------------------------------------------------------------------------------------+