diff --git a/docs/about/community.rst b/docs/about/community.rst new file mode 100644 index 0000000..cb44fd7 --- /dev/null +++ b/docs/about/community.rst @@ -0,0 +1,9 @@ +========= +Community +========= + +Discord +======= + +Contributors +============ \ No newline at end of file diff --git a/docs/about/features.rst b/docs/about/features.rst new file mode 100644 index 0000000..7e84d66 --- /dev/null +++ b/docs/about/features.rst @@ -0,0 +1,15 @@ +============ +Key Features +============ + +Collaboration +============= + +Session management +================== + +Easier communication +==================== + +Sync Datablocks +=============== \ No newline at end of file diff --git a/docs/about/index.rst b/docs/about/index.rst index 45794d2..4c6b092 100644 --- a/docs/about/index.rst +++ b/docs/about/index.rst @@ -1,10 +1,10 @@ - -##### -About -##### +================ +About Multi-User +================ .. toctree:: - :maxdepth: 1 - :name: toc-about + :maxdepth: 2 - introduction.rst + introduction + features + community diff --git a/docs/about/introduction.rst b/docs/about/introduction.rst index 538d0bc..097f191 100644 --- a/docs/about/introduction.rst +++ b/docs/about/introduction.rst @@ -1,7 +1,4 @@ -=============== -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 diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst index e9dc553..7abf939 100644 --- a/docs/advanced/index.rst +++ b/docs/advanced/index.rst @@ -14,4 +14,105 @@ Side Pannel Presence ========= -ui \ 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 + +------- +Network +------- + +.. 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. + +----- +Cache +----- + +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. + +--- +Log +--- + +.. 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: diff --git a/docs/conf.py b/docs/conf.py index ba3abcb..9825403 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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": # " v 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"] diff --git a/docs/getting_started/firstlaunch.rst b/docs/getting_started/firstlaunch.rst deleted file mode 100644 index b1e8452..0000000 --- a/docs/getting_started/firstlaunch.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _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 diff --git a/docs/getting_started/glossary.rst b/docs/getting_started/glossary.rst deleted file mode 100644 index 81bd4bc..0000000 --- a/docs/getting_started/glossary.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/getting_started/how-to-host.rst b/docs/getting_started/how-to-host.rst new file mode 100644 index 0000000..2bc272e --- /dev/null +++ b/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:`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 diff --git a/docs/getting_started/how-to-join.rst b/docs/getting_started/how-to-join.rst new file mode 100644 index 0000000..739001e --- /dev/null +++ b/docs/getting_started/how-to-join.rst @@ -0,0 +1,108 @@ +.. _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. + + .. figure:: img/server_preset_image_report.png + :align: center + :width: 200px + +---------------- +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 \ No newline at end of file diff --git a/docs/getting_started/how-to-manage.rst b/docs/getting_started/how-to-manage.rst new file mode 100644 index 0000000..a2a651e --- /dev/null +++ b/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 `_ . + +-------------------- +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 diff --git a/docs/getting_started/img/quickstart_connect.png b/docs/getting_started/img/quickstart_connect.png new file mode 100644 index 0000000..b496d23 Binary files /dev/null and b/docs/getting_started/img/quickstart_connect.png differ diff --git a/docs/getting_started/img/quickstart_host.png b/docs/getting_started/img/quickstart_host.png index 1f363a6..024dfd9 100644 Binary files a/docs/getting_started/img/quickstart_host.png and b/docs/getting_started/img/quickstart_host.png differ diff --git a/docs/getting_started/img/quickstart_lobby.png b/docs/getting_started/img/quickstart_lobby.png new file mode 100644 index 0000000..5d5f51e Binary files /dev/null and b/docs/getting_started/img/quickstart_lobby.png differ diff --git a/docs/getting_started/img/quickstart_lobby_wait.png b/docs/getting_started/img/quickstart_lobby_wait.png new file mode 100644 index 0000000..9201212 Binary files /dev/null and b/docs/getting_started/img/quickstart_lobby_wait.png differ diff --git a/docs/getting_started/img/quickstart_repository.png b/docs/getting_started/img/quickstart_repository.png new file mode 100644 index 0000000..002a1fb Binary files /dev/null and b/docs/getting_started/img/quickstart_repository.png differ diff --git a/docs/getting_started/img/quickstart_snap_camera.gif b/docs/getting_started/img/quickstart_snap_camera.gif new file mode 100644 index 0000000..158fb22 Binary files /dev/null and b/docs/getting_started/img/quickstart_snap_camera.gif differ diff --git a/docs/getting_started/img/quickstart_snap_time.gif b/docs/getting_started/img/quickstart_snap_time.gif index 134300c..b96a3a3 100644 Binary files a/docs/getting_started/img/quickstart_snap_time.gif and b/docs/getting_started/img/quickstart_snap_time.gif differ diff --git a/docs/getting_started/img/quickstart_synchronize.png b/docs/getting_started/img/quickstart_synchronize.png new file mode 100644 index 0000000..d0f0e66 Binary files /dev/null and b/docs/getting_started/img/quickstart_synchronize.png differ diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 72d1107..1c0576a 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -7,7 +7,9 @@ Getting started install update - firstlaunch quickstart + how-to-join + how-to-host + how-to-manage troubleshooting glossary diff --git a/docs/getting_started/install.rst b/docs/getting_started/install.rst index 9ba24e6..9637bf2 100644 --- a/docs/getting_started/install.rst +++ b/docs/getting_started/install.rst @@ -2,6 +2,8 @@ Installing Multi-User ===================== +.. warning:: Under development, use it at your own risks. + Multi-User is often updated. You can keep up to date with the latest changes through the release notes on our `Discord Server `_. Download @@ -22,7 +24,7 @@ Install 1. Download the addon zip file 2. Run blender as administrator (to allow python dependencies auto-installation). -3. Install **multi-user.zip** from your addon preferences (Edit >> Preferences >> Add-ons >> Install). +3. Install **multi-user.zip** from your addon preferences in :menuselection:`Edit --> Preferences --> Add-ons --> Install`. .. figure:: img/settings.png :align: center diff --git a/docs/getting_started/quickstart.rst b/docs/getting_started/quickstart.rst index 90f3691..92c18d8 100644 --- a/docs/getting_started/quickstart.rst +++ b/docs/getting_started/quickstart.rst @@ -1,11 +1,40 @@ .. _quickstart: -=========== -Quick start +Quick Start =========== -.. hint:: - *All session-related settings are located under: `View3D -> Sidebar -> Multiuser panel`* +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 :menuselection:`Edit --> Prerecences --> Add-ons --> Multi-user` or in :menuselection:`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. +- **General Settings**: Include advanced addon settings like *user info*, *server ping*, *cache*, etc. + +Session management +------------------ 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: @@ -14,469 +43,6 @@ In this guide, you will quickly learn how to use the collaborative session manag - :ref:`how-to-host` - :ref:`how-to-manage` -.. _how-to-join: +For more details on what the addon offers: -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. - - .. 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. - - .. figure:: img/server_preset_image_report.png - :align: center - :width: 200px - -.. note:: - Additional configuration settings can be found in the :ref:`advanced` section. - ----------------- -Joining a server ----------------- - -CONNECT -------- - -When joining a session that have already be initialise, the session status screen will be **CONNECT**. -You are now connected and can start creating. - - -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. -If you are the admin, you just need to initialise the session to start it (see image below). - -.. figure:: img/quickstart_session_init.png - :align: center - - Session initialisation for dedicated server - -During an online session, various actions are available to you. Go to :ref:`how-to-manage` to -learn more about them. - - -.. _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. - -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. - -.. _local-setup: - -Set up a local server ---------------------- - -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. - -.. 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. - -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` - -During an online session, various actions are available to you, go to :ref:`how-to-manage` section to -learn more about them. - - - -.. _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 `_ . - ---------------------------- -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_replication.png - :align: center - - Session replication flags - --------------------- -Monitor online users --------------------- - -One of the most vital tools is the **Online user panel**. It lists all connected -users' information including your own: - -* **Role** : if a user is an admin or a regular user. -* **Username** : Name of the user. -* **Mode** : User's active editing mode (edit_mesh, paint,etc.). -* **Frame**: When (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_view.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 users display --------------------- - -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 -* User active mode -* User selection - -.. figure:: img/quickstart_presence.png - :align: center - - Presence show flags - -The presence overlay panel (see image above) allows you to enable/disable -various drawn parts via the following flags: - -- **Show session status**: display the session status in the viewport - - .. figure:: img/quickstart_status.png - :align: center - - - **Text scale**: session status text size - - **Vertical/Horizontal position**: session position in the viewport - -- **Show selected objects**: display other users' current selections -- **Show users**: display users' current viewpoint -- **Show different scenes**: display users working on other scenes - - - ------------ -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_save_session_data.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 | -+---------------------------------------+-------------------+------------------------------------------------------------------------------------+ - -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: - -Advanced settings -================= - -This section contains optional settings to configure the session behavior. - -.. figure:: img/quickstart_advanced.png - :align: center - - Advanced configuration panel - -------- -Network -------- - -.. 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. - -.. _replication: - ------------ -Replication ------------ - -.. figure:: img/quickstart_advanced_replication.png - :align: center - - Advanced replication settings - -**Synchronize render settings** (only host) enable replication of EEVEE and CYCLES render settings to match renders between clients. - -**Synchronize active camera** sync the scene's active camera. - -**Edit Mode Updates** enable objects to update while you are in Edit_Mode. - -.. warning:: Edit Mode Updates kills the session's performance with complex objects (heavy meshes, gpencil, etc...). - -**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. -- **Despgraph ⚠️**: Use the blender dependency graph to trigger updates. Faster but experimental and unstable ! - -**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) - ------ -Cache ------ - -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. - ---- -Log ---- - -.. 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 | -+-----------+-----------------------------------------------+ \ No newline at end of file +.. - :ref: \ No newline at end of file diff --git a/docs/getting_started/troubleshooting.rst b/docs/getting_started/troubleshooting.rst deleted file mode 100644 index 0420833..0000000 --- a/docs/getting_started/troubleshooting.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _troubleshooting: - -=============== -Troubleshooting -=============== - -The majority of issues new users experience when first using Multi-User can be solved with a few quick checks. - -- Run Blender in Administrator mode -- Update the multi-user addon to the latest version -- Make sure to allow Blender through your firewall - - .. hint:: Your firewall may have additional settings like Ransomware protection, or you may need to enable both Blender and Python on private and/or public Networks - -- Solve problems with your connection quality -- Minimise the use of large textures or file sizes -- Avoid using 'Undo'. Use 'delete' instead - -Use the #support channel on the multi-user `discord server `_ to chat, seek help and contribute. \ No newline at end of file diff --git a/docs/glossary/index.rst b/docs/glossary/index.rst index e3b283e..81bd4bc 100644 --- a/docs/glossary/index.rst +++ b/docs/glossary/index.rst @@ -1,17 +1,59 @@ -############### -User Interface -############### +======== +Glossary +======== -Side Pannel -=========== -.. toctree:: - :maxdepth: 1 - - Introduction - server/splash.rst +.. glossary:: -Presence -========= + .. _admin: + + administrator -ui \ No newline at end of file + *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 diff --git a/docs/img/homepage_ban.png b/docs/img/homepage_ban.png index 8ea2aaf..3164e40 100644 Binary files a/docs/img/homepage_ban.png and b/docs/img/homepage_ban.png differ diff --git a/docs/index.rst b/docs/index.rst index a0dd864..95ee32d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,9 @@ Multi-user 0.5.0 Reference Manual Welcome to the manual of the Multi-user, a free and open source blender addon. It tool aims to bring multiple users to work on the same .blend over the network. -.. image:: img/homepage_ban.png +Join our `discord server `_ to get help and join collaborative creation sessions. -.. warning:: Under development, use it at your own risks. +.. image:: img/homepage_ban.png Getting started @@ -20,7 +20,7 @@ Getting started .. container:: descr - :doc:`about/introduction` + :doc:`about/index` .. container:: descr @@ -32,7 +32,7 @@ Getting started .. container:: descr - :doc:`getting_started/troubleshooting` + :doc:`troubleshooting/index` Sections @@ -80,64 +80,13 @@ Sections .. toctree:: :maxdepth: 1 + about/index.rst getting_started/index.rst ui/index.rst advanced/index.rst hosting_internet/index.rst workflow/index.rst + troubleshooting/index.rst + ways_to_contribute/index.rst + glossary/index.rst - -.. Main Features -.. ============= - -.. - Collaborative workflow in blender -.. - Viewport users presence (active selection, POV) -.. - Datablocks right managment -.. - Tested under Windows - -.. Community -.. ========= - -.. A `discord server `_ have been created to provide help for new users and -.. organize collaborative creation sessions. - -.. Status -.. ====== - -.. .. image:: img/homepage_roadmap.png - - -.. Follow the `roadmap `_ to be aware of last news. - -.. Documentation is organized into the following sections: - -.. .. toctree:: -.. :maxdepth: 1 -.. :caption: About -.. :name: sec-about - -.. about/introduction - -.. .. toctree:: -.. :maxdepth: 1 -.. :caption: Getting started -.. :name: sec-learn - -.. getting_started/install -.. getting_started/quickstart -.. getting_started/glossary -.. getting_started/troubleshooting - -.. .. toctree:: -.. :maxdepth: 1 -.. :caption: Tutorials -.. :name: sec-tutorials - -.. tutorials/hosting_guide - -.. .. toctree:: -.. :maxdepth: 1 -.. :caption: Community -.. :name: sec-community - -.. ways_to_contribute \ No newline at end of file diff --git a/docs/resources/favicon.ico b/docs/resources/favicon.ico new file mode 100644 index 0000000..d54a139 Binary files /dev/null and b/docs/resources/favicon.ico differ diff --git a/docs/resources/logo.png b/docs/resources/logo.png new file mode 100644 index 0000000..9ea2407 Binary files /dev/null and b/docs/resources/logo.png differ diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst index e3b283e..294ef31 100644 --- a/docs/troubleshooting/index.rst +++ b/docs/troubleshooting/index.rst @@ -1,17 +1,17 @@ -############### -User Interface -############### +.. _troubleshooting: -Side Pannel -=========== +=============== +Troubleshooting +=============== -.. toctree:: - :maxdepth: 1 - - Introduction - server/splash.rst +The majority of issues new users experience when first using Multi-User can be solved with a few quick checks. -Presence -========= +- Update the multi-user addon to the latest version +- Make sure to allow Blender through your firewall + + .. hint:: Your firewall may have additional settings like Ransomware protection, or you may need to enable both Blender and Python on private and/or public Networks -ui \ No newline at end of file +- Solve problems with your connection quality +- Minimise the use of large textures or file sizes + +Use the #support channel on the multi-user `discord server `_ to chat, seek help and contribute. \ No newline at end of file diff --git a/docs/ui/index.rst b/docs/ui/index.rst index e3b283e..6a21ec8 100644 --- a/docs/ui/index.rst +++ b/docs/ui/index.rst @@ -14,4 +14,33 @@ Side Pannel Presence ========= -ui \ No newline at end of file +Change users display +-------------------- + +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 +* User active mode +* User selection + +.. figure:: img/quickstart_presence.png + :align: center + + Presence show flags + +The presence overlay panel (see image above) allows you to enable/disable +various drawn parts via the following flags: + +- **Show session status**: display the session status in the viewport + + .. figure:: img/quickstart_status.png + :align: center + + - **Text scale**: session status text size + - **Vertical/Horizontal position**: session position in the viewport + +- **Show selected objects**: display other users' current selections +- **Show users**: display users' current viewpoint +- **Show different scenes**: display users working on other scenes \ No newline at end of file diff --git a/docs/ways_to_contribute.rst b/docs/ways_to_contribute/index.rst similarity index 98% rename from docs/ways_to_contribute.rst rename to docs/ways_to_contribute/index.rst index 1118952..000e0fe 100644 --- a/docs/ways_to_contribute.rst +++ b/docs/ways_to_contribute/index.rst @@ -1,6 +1,8 @@ -================== +.. _ways-to-contribute: + +################## Ways to contribute -================== +################## .. Note:: Work in progress