doc: quickstart revamp

refactor: ttl start on connection

docs/getting_started/quickstart.rst

@@ -1,70 +1,121 @@
 ===========
-Quick start guide
+Quick start
 ===========
 
-*All settings are located under: `View3D -> Sidebar -> Multiuser panel`*
+.. hint::
+   *All settings are located under: `View3D -> Sidebar -> Multiuser panel`*
 
-Session setup
+The multi-user is based on a session management system. Under the 
-=============
+In this this guide you will learn how to master the collaborative session system in three part:
-This section describe how to create or join a collaborative session.
 
----------------------
+- :ref:`how-to-host`
-1. User information's
+- :ref:`how-to-join`
----------------------
+- :ref:`how-to-manage`
 
-.. image:: img/quickstart_user_infos.png
 
-- **name**: username.
+.. _how-to-host:
-- **color**: color used to represent the user into other user workspace.
 
-----------
+How to host a session
-2. Network
+=====================
-----------
 
-.. note:: If you host a session over internet, special network configuration is needed. 
+TODO: Speak about local/DEDICATED HERE
+
+.. _user-info:
+
+-----------------------------
+1. Fill your user information
+-----------------------------
+
+In the **User Info** panel (See image below) allow you to constomize your online identity.
+
+.. figure:: img/quickstart_user_info.png
+   :align: center
+
+   User info panel
+
+
+Let's fill those tow field:
+
+- **name**: your online name.
+- **color**: a color used to represent you into other user workspace(see image below).
+
+
+During online sessions, other users will see your selected object and camera hilghlited in your profile color.
+
+.. _user-representation:
+
+.. figure:: img/quickstart_user_representation.png
+   :align: center
+
+   User viewport representation
+
+--------------------
+2. Setup the network
+--------------------
+
+When the hosting process will start, the multi-user addon will lauch a local server instance.
+The **Host panel**(see image below) allow you to configure this server according to:
+
+* **Port**: Port on wich the server is listening
+* **Start from**: The session initialisation method
+
+   * **current scenes**: start with the current blendfile datas
+   * **an empty scene**: clear a data and start over
+   .. danger::
+      By starting from an empty, all of the blend data will be removed !
+      Ensure to save your existing work before launching the session.
+
+* **Admin password**: The session administration password
+
+.. figure:: img/quickstart_host.png 
+   :align: center
+   :alt: host menu
+
+   Host network panel
+
+
+.. note:: Additionnal configuration setting can be found in the :ref:`advanced` section.
+
+Once everything is setup you can hit the **HOST** button to launch the session !
+
+It will start the server and connect to it in few steps.
+
+
+.. _how-to-join:
+
+How to join a session
+=====================
+
+This section describe how join a session.
+
+-----------------------------
+1. Fill your user information
+-----------------------------
+
+Follow the user-info_ section for this step.
+
+----------------
+2. Network setup
+----------------
+
+Connection are done from this panel.
+
+.. image:: img/quickstart_join.png
+   :align: center
+   
+IP: server ip
+Port: server port 
 
-Hosting and connection are done from this panel.
- 
-+-----------------------------------+-------------------------------------+
-| Host                              | Join                                |
-+===================================+=====================================+
-|.. image:: img/quickstart_host.png | .. image:: img/quickstart_join.png  |
-+-----------------------------------+-------------------------------------+
-| | Start empty: Cleanup the file   | | IP: server ip                     |
-| | before hosting                  | | Port: server port                 |
-+-----------------------------------+-------------------------------------+
-|  **HOST**: Host a session         | **CONNECT**: Join a session         |
-+-----------------------------------+-------------------------------------+
 
 **Port configuration:**
 For now, a session use 4 ports to run.
 
----------------------
-2.1 Advanced settings
----------------------
 
-This section contains optionnal settings to configure the session behavior.
 
-.. image:: img/quickstart_advanced.png
+.. _how-to-manage:
 
-**Synchronise render settings** (only host) enable replication of EEVEE and CYCLES render settings to match render between clients.
+How to manage a session
- 
+=======================
-**Right strategy** (only host) enable you to choose between a strict and a relaxed pattern:
-
-- **Strict**: Host is the king, by default the host own each properties, only him can grant modification rights.
-- **Common**: Each properties are under common rights by default, on selection, a property is only modifiable by the owner.
-  
-On each strategy, when a user is the owner he can choose to pass his rights to someone else.
-
-**Properties frequency gird** allow to 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)
-
-.. note:: Per-data type settings will soon be revamped for simplification purposes
-
-Session Management
-==================
 
 This section describe tools available during a collaborative session.
 
@@ -73,6 +124,7 @@ Connected users
 ---------------
 
 .. image:: img/quickstart_users.png
+   :align: center
 
 This panel displays all connected users information's, including yours. 
 By selecting a user in the list you'll have access to different **actions**:
@@ -116,7 +168,22 @@ Since the replication architecture is based on commit/push/pull mechanisms, a re
 | .. image:: img/quickstart_remove.png  |  **Delete**       | Remove the data-block from network replication                                     |
 +---------------------------------------+-------------------+------------------------------------------------------------------------------------+
 
-
+.. _advanced:
+
+Advanced configuration
+======================
+
+This section contains optionnal settings to configure the session behavior.
+
+.. image:: img/quickstart_advanced.png
+
+**Synchronise render settings** (only host) enable replication of EEVEE and CYCLES render settings to match render between clients.
+
+**Properties frequency gird** allow to 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)
+
+.. note:: Per-data type settings will soon be revamped for simplification purposes
 
 
 

multi_user/preferences.py

@@ -93,10 +93,13 @@ class SessionPrefs(bpy.types.AddonPreferences):
         description='internal ttl port(only usefull for multiple local instances)',
         default=5561
     )
-    start_empty: bpy.props.BoolProperty(
+    init_method: bpy.props.EnumProperty(
-        name="start_empty",
+        name='init_method',
-        default=False
+        description='Init repo',
-    )
+        items={
+            ('EMPTY', 'an empty scene', 'start empty'),
+            ('BLEND', 'current scenes', 'use current scenes')},
+        default='BLEND')
     cache_directory: bpy.props.StringProperty(
         name="cache directory",
         subtype="DIR_PATH",
@@ -229,8 +232,8 @@ class SessionPrefs(bpy.types.AddonPreferences):
                 row.label(text="Port:")
                 row.prop(self, "port", text="Address")
                 row = box.row()
-                row.label(text="Start with an empty scene:")
+                row.label(text="Init the session from:")
-                row.prop(self, "start_empty", text="")
+                row.prop(self, "init_method", text="")
 
                 table = box.box()
                 table.row().prop(
@@ -258,8 +261,8 @@ class SessionPrefs(bpy.types.AddonPreferences):
                 else 'DISCLOSURE_TRI_RIGHT', emboss=False)
             if self.conf_session_hosting_expanded:
                 row = box.row()
-                row.label(text="Start with an empty scene:")
+                row.label(text="Init the session from:")
-                row.prop(self, "start_empty", text="")
+                row.prop(self, "init_method", text="")
 
             # CACHE SETTINGS
             box = grid.box()

multi_user/ui.py

@@ -197,6 +197,9 @@ class SESSION_PT_settings_network(bpy.types.Panel):
             row.label(text="Port:")
             row.prop(settings, "port", text="")
             row = box.row()
+            row.label(text="Start from:")
+            row.prop(settings, "init_method", text="")
+            row = box.row()
             row.label(text="Admin password:")
             row.prop(runtime_settings, "password", text="")
             row = box.row()
@@ -207,6 +210,7 @@ class SESSION_PT_settings_network(bpy.types.Panel):
             row = box.row()
             row.label(text="Port:")
             row.prop(settings, "port", text="")
+
             row = box.row()
             row.prop(runtime_settings, "admin", text='Connect as admin', icon='DISCLOSURE_TRI_DOWN' if runtime_settings.admin
                      else 'DISCLOSURE_TRI_RIGHT')