Merge branch 'develop' into 'master'

fix: auto-updater operators registration to ensure blender 2.93 compatibility

See merge request slumber/multi-user!117

.gitignore

@@ -7,6 +7,10 @@ __pycache__/
 cache
 config
 *.code-workspace
+multi_user_updater/
 
 # sphinx build folder
-_build
+_build
+
+# ignore generated zip generated from blender_addon_tester
+*.zip

.gitlab-ci.yml

@@ -0,0 +1,13 @@
+stages:
+  - test
+  - build
+  - deploy
+  - doc
+
+
+
+include:
+  - local: .gitlab/ci/test.gitlab-ci.yml
+  - local: .gitlab/ci/build.gitlab-ci.yml
+  - local: .gitlab/ci/deploy.gitlab-ci.yml
+  - local: .gitlab/ci/doc.gitlab-ci.yml

.gitlab/ci/build.gitlab-ci.yml

@@ -0,0 +1,10 @@
+build:
+  stage: build
+  needs: ["test"]
+  image: debian:stable-slim
+  script:
+    - rm -rf tests .git .gitignore script
+  artifacts:
+    name: multi_user
+    paths: 
+     - multi_user

.gitlab/ci/deploy.gitlab-ci.yml

@@ -0,0 +1,20 @@
+deploy:
+  stage: deploy
+  needs: ["build"]
+  image: slumber/docker-python  
+  variables:
+    DOCKER_DRIVER: overlay2
+    DOCKER_TLS_CERTDIR: "/certs"
+  
+  services:
+  - docker:19.03.12-dind
+
+  script:
+    - RP_VERSION="$(python scripts/get_replication_version.py)"
+    - VERSION="$(python scripts/get_addon_version.py)"
+    - echo "Building docker image with replication ${RP_VERSION}"
+    - docker build --build-arg replication_version=${RP_VERSION}  --build-arg version={VERSION} -t registry.gitlab.com/slumber/multi-user/multi-user-server:${VERSION} ./scripts/docker_server
+    - echo "Pushing to gitlab registry ${VERSION}"
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+    - docker tag registry.gitlab.com/slumber/multi-user/multi-user-server:${VERSION} registry.gitlab.com/slumber/multi-user/multi-user-server:${CI_COMMIT_REF_NAME}
+    - docker push registry.gitlab.com/slumber/multi-user/multi-user-server

.gitlab/ci/doc.gitlab-ci.yml

@@ -0,0 +1,16 @@
+pages:
+  stage: doc
+  needs: ["deploy"]
+  image: python
+  script:
+  - pip install -U sphinx sphinx_rtd_theme sphinx-material
+  - sphinx-build -b html ./docs public
+  artifacts:
+    paths:
+    - public
+  only:
+    refs:
+    - master
+    - develop
+
+

.gitlab/ci/test.gitlab-ci.yml

@@ -0,0 +1,5 @@
+test:
+  stage: test
+  image: slumber/blender-addon-testing:latest
+  script:
+    - python3 scripts/test_addon.py

.gitlab/issue_templates/Bug.md

@@ -0,0 +1,46 @@
+<!---
+Please read this!
+
+Before opening a new issue, make sure to search for keywords in the issues
+filtered by the "bug" label:
+
+- https://gitlab.com/slumber/multi-user/-/issues?scope=all&utf8=✓&label_name[]=bug
+
+and verify the issue you're about to submit isn't a duplicate.
+--->
+
+### Summary
+
+(Summarize the bug encountered concisely)
+
+* Addon version: (your addon-version)
+* Blender version: (your blender version)
+* OS: (your os windows/linux/mac)
+
+
+### Steps to reproduce
+
+(How one can reproduce the issue - this is very important)
+
+###  Example Project [optionnal]
+(If possible, please create an example project  that exhibits the problematic behavior, and link to it here in the bug report)
+
+
+### What is the current *bug* behavior?
+
+(What actually happens)
+
+
+### Relevant logs and/or screenshots
+
+(Paste any relevant logs - please use code blocks (```) to format console output,
+logs, and code as it's tough to read otherwise.)
+
+
+### Possible fixes [optionnal]
+
+(If you can, link to the line of code that might be responsible for the problem)
+
+
+/label ~type::bug
+/cc @project-manager

.gitlab/issue_templates/Documentation.md

@@ -0,0 +1,30 @@
+### Problem to solve
+
+<!-- Include the following detail as necessary:
+* What feature(s) affected?
+* What docs or doc section affected? Include links or paths.
+* Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs?
+* Any other ideas or requests?
+-->
+
+### Further details
+
+<!--
+* Any concepts, procedures, reference info we could add to make it easier to successfully use the multi-user addom?
+* Include use cases, benefits, and/or goals for this work.
+-->
+
+### Proposal
+
+<!-- Further specifics for how can we solve the problem. -->
+
+### Who can address the issue
+
+<!-- What if any special expertise is required to resolve this issue? -->
+
+### Other links/references
+
+<!-- E.g. related GitLab issues/MRs -->
+
+/label ~type::documentation
+/cc @project-manager

.gitlab/issue_templates/Feature Proposal.md

@@ -0,0 +1,18 @@
+### Problem to solve
+
+<!-- What problem do we solve? Try to define the who/what/why of the opportunity as a user story. For example, "As a (who), I want (what), so I can (why/value)." -->
+
+
+### Proposal
+
+<!-- How are we going to solve the problem?-->
+
+### Further details
+
+<!-- Include use cases, benefits, goals, or any other details that will help us understand the problem better. -->
+
+
+### Links / references
+
+/label ~type::feature request
+/cc @project-manager

.gitlab/issue_templates/Refactoring.md

@@ -0,0 +1,34 @@
+## Summary
+
+<!--
+Please briefly describe what part of the code base needs to be refactored.
+-->
+
+## Improvements
+
+<!--
+Explain the benefits of refactoring this code.
+-->
+
+## Risks
+
+<!--
+Please list features that can break because of this refactoring and how you intend to solve that.
+-->
+
+## Involved components
+
+<!--
+List files or directories that will be changed by the refactoring.
+-->
+
+## Optional: Intended side effects
+
+<!--
+If the refactoring involves changes apart from the main improvements (such as a better UI), list them here.
+It may be a good idea to create separate issues and link them here.
+-->
+
+
+/label ~type::refactoring
+/cc @project-manager

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "multi_user/libs/replication"]
-	path = multi_user/libs/replication
-	url = https://gitlab.com/slumber/replication.git

CHANGELOG.md

@@ -35,4 +35,155 @@ All notable changes to this project will be documented in this file.
 - Right management takes view-layer in account for object selection.
 - Use a basic BFS approach for replication graph pre-load.
 - Serialization is now based on marshal (2x performance improvements).
-- Let pip chose python dependencies install path.
+- Let pip chose python dependencies install path.
+
+## [0.0.3] - 2020-07-29
+
+### Added
+
+- Auto updater support
+- Big Performances improvements on Meshes, Gpencils, Actions
+- Multi-scene workflow support
+- Render setting synchronization
+- Kick command
+- Dedicated server with a basic command set
+- Administrator session status
+- Tests
+- Blender 2.83-2.90 support
+
+### Changed
+
+- Config is now stored in blender user preference
+- Documentation update
+- Connection protocol
+- UI revamp:
+  - user localization
+  - repository init
+
+### Removed
+
+- Unused strict right management strategy
+- Legacy config management system
+
+## [0.1.0] - 2020-10-05
+
+### Added
+
+- Dependency graph driven updates [experimental]
+- Edit Mode updates
+- Late join mechanism 
+- Sync Axis lock replication
+- Sync collection offset
+- Sync camera  orthographic scale
+- Sync custom fonts
+- Sync sound files
+- Logging configuration (file output and level)
+- Object visibility type replication
+- Optionnal sync for active camera
+- Curve->Mesh conversion
+- Mesh->gpencil conversion
+
+### Changed
+
+- Auto updater now handle installation from branches
+- Use uuid for collection loading
+- Moved session instance to replication package
+
+### Fixed
+
+- Prevent unsupported data types to crash the session
+- Modifier vertex group assignation
+- World sync
+- Snapshot UUID error
+- The world is not synchronized
+
+## [0.1.1] - 2020-10-16
+
+### Added
+
+- Session status widget
+- Affect dependencies during change owner
+- Dedicated server managment scripts(@brybalicious)
+
+### Changed
+
+- Refactored presence.py
+- Reset button UI icon 
+- Documentation `How to contribute` improvements (@brybalicious)
+- Documentation `Hosting guide` improvements (@brybalicious)
+- Show flags are now available from the viewport overlay
+ 
+### Fixed
+
+- Render sync race condition (causing scene errors)
+- Binary differentials
+- Hybrid session crashes between Linux/Windows
+- Materials node default output value
+- Right selection
+- Client node rights changed to COMMON after disconnecting from the server 
+- Collection instances selection draw
+- Packed image save error
+- Material replication
+- UI spelling errors (@brybalicious)
+
+
+## [0.2.0] - 2020-12-17
+
+### Added
+
+- Documentation `Troubleshouting` section (@brybalicious)
+- Documentation `Update` section (@brybalicious)
+- Documentation `Cloud Hosting Walkthrough` (@brybalicious)
+- Support DNS name
+- Sync annotations
+- Sync volume objects
+- Sync material node_goups 
+- Sync VSE
+- Sync grease pencil modifiers
+- Sync textures (modifier only)
+- Session status widget
+- Disconnection popup 
+- Popup with disconnection reason 
+
+
+### Changed
+
+- Improved GPencil performances
+
+### Fixed
+
+- Texture paint update
+- Various documentation fixes section (@brybalicious)
+- Empty and Light object selection highlights
+- Material renaming
+- Default material nodes input parameters
+- blender 2.91 python api compatibility
+
+## [0.3.0] - 2021-04-14
+
+### Added
+
+- Curve material support
+- Cycle visibility settings
+- Session save/load  operator 
+- Add new scene support
+- Physic initial support
+- Geometry node initial support
+- Blender 2.93 compatibility
+### Changed
+
+- Host documentation on Gitlab Page
+- Event driven update (from the blender deps graph)
+
+### Fixed
+
+- Vertex group assignation
+- Parent relation can't be removed
+- Separate object
+- Delete animation
+- Sync missing holdout option for grease pencil material
+- Sync missing `skin_vertices`  
+- Exception access violation during Undo/Redo
+- Sync missing armature bone Roll
+- Sync missing driver data_path
+- Constraint replication

README.md

@@ -2,7 +2,7 @@
 
 > Enable real-time collaborative workflow inside blender  
 
-![demo](https://i.imgur.com/X0B7O1Q.gif)
+<img src="https://i.imgur.com/X0B7O1Q.gif" width=600>
 
 
 :warning: Under development, use it at your own risks. Currently tested on Windows platform. :warning:
@@ -11,7 +11,7 @@ This tool aims to allow multiple users to work on the same scene over the networ
 
 ## Quick installation
 
-1. Download latest release [multi_user.zip](/uploads/8aef79c7cf5b1d9606dc58307fd9ad8b/multi_user.zip).
+1. Download latest release [multi_user.zip](https://gitlab.com/slumber/multi-user/-/jobs/artifacts/master/download?job=build).
 2. Run blender as administrator (dependencies installation).
 3. Install last_version.zip from your addon preferences.
 
@@ -19,28 +19,47 @@ This tool aims to allow multiple users to work on the same scene over the networ
 
 ## Usage
 
-See the [documentation](https://multi-user.readthedocs.io/en/latest/) for details.
+See the [documentation](https://slumber.gitlab.io/multi-user/index.html) for details.
+
+## Troubleshooting
+
+See the [troubleshooting guide](https://slumber.gitlab.io/multi-user/getting_started/troubleshooting.html) for tips on the most common issues.
 
 ## Current development status
 
 Currently, not all data-block are supported for replication over the wire. The following list summarizes the status for each ones.
 
-| Name        |       Status       |    Comment     |
-| ----------- | :----------------: | :------------: |
-| action      |   :exclamation:    |   Not stable   |
-| armature    |   :exclamation:    |   Not stable   |
-| camera      | :white_check_mark: |                |
-| collection  | :white_check_mark: |                |
-| curve       | :white_check_mark: |   Not tested   |
-| gpencil     | :white_check_mark: |                |
-| image       |   :exclamation:    | Not stable yet |
-| mesh        | :white_check_mark: |                |
-| material    | :white_check_mark: |                |
-| metaball    | :white_check_mark: |                |
-| object      | :white_check_mark: |                |
-| scene       | :white_check_mark: |                |
-| world       | :white_check_mark: |                |
-| lightprobes | :white_check_mark: |                |
+| Name           | Status |                           Comment                            |
+| -------------- | :----: | :----------------------------------------------------------: |
+| action         |   ✔️    |                                                              |
+| armature       |   ❗    |                          Not stable                          |
+| camera         |   ✔️    |                                                              |
+| collection     |   ✔️    |                                                              |
+| curve          |   ❗    |                 Nurbs surfaces not supported                 |
+| gpencil        |   ✔️    |                                                              |
+| image          |   ✔️    |                                                              |
+| mesh           |   ✔️    |                                                              |
+| material       |   ✔️    |                                                              |
+| node_groups    |   ❗    |                   Material & Geometry only                   |
+| geometry nodes |   ✔️    |                                                              |
+| metaball       |   ✔️    |                                                              |
+| object         |   ✔️    |                                                              |
+| textures       |   ❗    |       Supported for modifiers/materials/geo nodes only       |
+| texts          |   ✔️    |                                                              |
+| scene          |   ✔️    |                                                              |
+| world          |   ✔️    |                                                              |
+| lightprobes    |   ✔️    |                                                              |
+| compositing    |   ❌    | [Planned](https://gitlab.com/slumber/multi-user/-/issues/46) |
+| texts          |   ❌    | [Planned](https://gitlab.com/slumber/multi-user/-/issues/81) |
+| nla            |   ❌    |                                                              |
+| volumes        |   ✔️    |                                                              |
+| particles      |   ❗    |                   The cache isn't syncing.                   |
+| speakers       |   ❗    | [Partial](https://gitlab.com/slumber/multi-user/-/issues/65) |
+| vse            |   ❗    |               Mask and Clip not supported yet                |
+| physics        |   ❌    | [Planned](https://gitlab.com/slumber/multi-user/-/issues/45) |
+| libraries      |   ❗    |                           Partial                            |
+
+
 
 ### Performance issues
 
@@ -51,18 +70,17 @@ I'm working on it.
 
 | Dependencies | Version | Needed |
 | ------------ | :-----: | -----: |
-| ZeroMQ       | latest  |    yes |
-| msgpack      | latest  |    yes |
-| PyYAML       | latest  |    yes |
-| JsonDiff     | latest  |    yes |
+| Replication  | latest  |    yes |
+
 
 
 ## Contributing
 
-See [contributing section](https://multi-user.readthedocs.io/en/latest/ways_to_contribute.html) of the documentation.
+See [contributing section](https://slumber.gitlab.io/multi-user/ways_to_contribute.html) of the documentation.
+
+Feel free to [join the discord server](https://discord.gg/aBPvGws) to chat, seek help and contribute.
 
 ## Licensing
 
 See [license](LICENSE)
 
-[![Documentation Status](https://readthedocs.org/projects/multi-user/badge/?version=latest)](https://multi-user.readthedocs.io/en/latest/?badge=latest)

docs/about/introduction.rst

@@ -5,6 +5,11 @@ Introduction
 
 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.
 
+.. figure:: img/about_chain.gif
+    :align: center
+
+    The linear workflow problems
+
 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.

docs/conf.py

@@ -19,10 +19,10 @@ import sys
 
 project = 'multi-user'
 copyright = '2020, Swann Martinez'
-author = 'Swann Martinez'
+author = 'Swann Martinez, with contributions from Poochy'
 
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
+release = '0.2.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/getting_started/glossary.rst

@@ -0,0 +1,59 @@
+========
+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/index.rst

@@ -1,3 +1,4 @@
+===============
 Getting started
 ===============
 
@@ -7,3 +8,5 @@ Getting started
 
    install
    quickstart
+   troubleshooting
+   glossary

docs/getting_started/install.rst

@@ -2,8 +2,57 @@
 Installation
 ============
 
-*The process is the same for linux, mac and windows.*
+.. hint::
+    The process is the same for linux, mac and windows.
 
-1. Download latest release `multi_user.zip <https://gitlab.com/slumber/multi-user/uploads/8aef79c7cf5b1d9606dc58307fd9ad8b/multi_user.zip>`_.
+1. Download `LATEST build <https://gitlab.com/slumber/multi-user/-/jobs/artifacts/develop/download?job=build>`_ or `STABLE build <https://gitlab.com/slumber/multi-user/-/jobs/artifacts/master/download?job=build>`_.
 2. Run blender as administrator (to allow python dependencies auto-installation).
-3. Install last_version.zip from your addon preferences.
+3. Install **multi-user.zip** from your addon preferences.
+
+Once the addon is succesfully installed, I strongly recommend you to follow the :ref:`quickstart`
+tutorial.
+
+.. _update-version:
+
+Updates
+=======
+
+Multi-User has a built-in auto-update function.
+
+1. Navigate to Edit >> Preferences pane in Blender, and go to the 'Add-ons' section.
+2. Search 'multi-user', select the 'Update' tab, click 'Auto-check for Update' and choose the frequency you'd like.
+3. Make sure to click the three bars in the bottom-left, and save this to your preferences (userpref.blend).
+
+Sometimes you'd like to perform manual update, or even side-grade or rollback your multi-user version. Perhaps you are trying out new features from the 'develop' branch in a test session.
+
+1. Click on 'Check now for multiuser update'. Multi-user will now find new versions
+
+.. figure:: img/update_1.jpg
+    :align: center
+    :width: 300px
+
+    Check for updates
+
+2. Select 'Install latest master / old version'
+
+.. figure:: img/update_2.jpg
+    :align: center
+    :width: 300px
+
+    Install
+
+3. In most cases, select 'master' branch for the latest stable release. The unstable 'develop' branch and older releases are available
+
+.. figure:: img/update_3.jpg
+    :align: center
+    :width: 300px
+
+    Select version
+
+4. Finally, restart blender to use the updated version
+
+.. figure:: img/update_4.jpg
+    :align: center
+    :width: 300px
+
+    Restart blender

docs/getting_started/quickstart.rst

@@ -1,90 +1,309 @@
+.. _quickstart:
+
 ===========
 Quick start
 ===========
 
-*All settings are located under: `View3D -> Sidebar -> Multiuser panel`*
+.. hint::
+   *All session-related settings are located under: `View3D -> Sidebar -> Multiuser panel`*
 
-Session setup
-=============
-This section describe how to create or join a collaborative session.
+The multi-user addon provides a session management system.
+In this guide, you will quickly learn how to use the collaborative session management system in three parts:
+
+- :ref:`how-to-host`
+- :ref:`how-to-join`
+- :ref:`how-to-manage`
+
+.. _how-to-host:
+
+How to host a session
+=====================
+
+The multi-user add-on relies on a Client-Server architecture. 
+The server is the heart of the collaborative session.
+It is what allows user's blender instances to communicate with each other.  
+In simple terms, *Hosting a session* means *run a local server and connect the local client to it*. 
+When I say **local server** I 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, I strongly recommend that you read the :ref:`internet-guide` tutorial.
+
+.. _user-info:
+
+--------------------------------
+1. Fill in your user information
+--------------------------------
+
+The **User Info** panel (See image below) allows you to customise your online identity.
+
+.. figure:: img/quickstart_user_info.png
+   :align: center
+
+   User info panel
+
+
+Let's fill in those two fields:
+
+- **name**: your online name.
+- **color**: a color used to represent you in other users' workspaces (see image below).
+
+
+During online sessions, other users will see your selected object and camera highlighted in your profile color.
+
+.. _user-representation:
+
+.. figure:: img/quickstart_user_representation.png
+   :align: center
+
+   User viewport representation aka 'User Presence'
 
 ---------------------
-1. User information's
+2. Set up the network
 ---------------------
 
-.. image:: img/quickstart_user_infos.png
+When the hosting process starts, the multi-user addon will launch a local server instance.
+In the network panel, select **HOST**.
+The **Host sub-panel** (see image below) allows you to configure the server according to:
 
-- **name**: username.
-- **color**: color used to represent the user into other user workspace.
+* **Port**: Port on which the server is listening.
+* **Start from**: The session initialisation method.
 
-----------
-2. Network
-----------
+   * **current scenes**: Start with the data loaded in the current blend file.
+   * **an empty scene**: Clear the blend file's data and start over.
+   
+   .. danger::
+      By starting from an empty scene, all of the blend data will be removed!
+      Be sure to save your existing work before launching the session.
 
-.. note:: If you host a session over internet, special network configuration is needed. 
+* **Admin password**: The session administration password.
 
-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         |
-+-----------------------------------+-------------------------------------+
+.. figure:: img/quickstart_host.png 
+   :align: center
+   :alt: host menu
 
-**Port configuration:**
-For now, a session use 4 ports to run.
-If 5555 is given in host settings, it will use 5555, 5556 (5555+1), 5557 (5555+2), 5558 (5555+3). 
+   Host network panel
 
-------------
-2.1 Advanced
-------------
 
-.. image:: img/quickstart_advanced.png
+.. note:: Additional configuration setting can be found in the :ref:`advanced` section.
 
-**Right strategy** (only host) enable you to choose between a strict and a relaxed pattern:
+Once everything is set up, you can hit the **HOST** button to launch the session!
 
-- **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.
+This will do two things:
 
-**Properties frequency gird** allow to set a custom replication frequency for each type of data-block:
+* Start a local server 
+* Connect you to it as an :ref:`admin`
 
-- **Refresh**: pushed data update rate (in second)
-- **Apply**: pulled data update rate (in second)
+During an online session, various actions are available to you, go to :ref:`how-to-manage` section to 
+learn more about them.
 
-.. note:: Per-data type settings will soon be revamped for simplification purposes
+.. _how-to-join:
 
-Session Management
-==================
+How to join a session
+=====================
 
-This section describe tools available during a collaborative session.
+This section describes how join a launched session. 
+Before starting make sure that you have access to the session IP address and port number.
 
----------------
-Connected users
----------------
+--------------------------------
+1. Fill in your user information
+--------------------------------
 
-.. image:: img/quickstart_users.png
+Follow the user-info_ section for this step.
 
-This panel displays all connected users information's, including yours. 
-By selecting a user in the list you'll have access to different **actions**:
+----------------
+2. Network setup
+----------------
 
-- The **camera button** allow you to snap on the user viewpoint.
-- The **time button** allow you to snap on the user time.
+In the network panel, select **JOIN**.
+The **join sub-panel** (see image below) allows you to configure your client to join a
+collaborative session which is already hosted.
 
----------------------
-Replicated properties
----------------------
+.. figure:: img/quickstart_join.png
+   :align: center
+   :alt: Connect menu
 
-.. image:: img/quickstart_properties.png
+   Connection panel
 
-The **replicated properties** panel shows all replicated properties status and associated actions.
-Since the replication architecture is based on commit/push/pull mechanisms, a replicated properties can be pushed/pull or even committed manually from this panel.
+Fill in the fields with your information:
+
+- **IP**: the host's IP address.
+- **Port**: the host's port number.
+- **Connect as admin**: connect yourself with **admin rights** (see :ref:`admin` ) to the session.
+
+.. Maybe something more explicit here
+
+.. note::
+   Additional configuration settings can be found in the :ref:`advanced` section.
+
+Once you've configured every field, hit the button **CONNECT** to join the session !
+When the :ref:`session-status` is **ONLINE** you are online and ready to start co-creating.
+
+.. note::
+   When starting a **dedicated server**, the session status screen will take you to the **LOBBY**, awaiting an admin to start the session.
+
+   If the session status is set to **LOBBY** and you are a regular user, you need to wait for the admin to launch the scene.
+   If you are the admin, you just need to initialise the repository to start the session (see image below).
+
+   .. figure:: img/quickstart_session_init.png
+      :align: center
+
+      Session initialisation for dedicated server
+
+During an online session, various actions are available to you. Go to :ref:`how-to-manage` 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 <https://gitlab.com/slumber/multi-user/-/issues/75>`_ .
+
+---------------------------
+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.
+* **Location**: Where the user is actually working.
+* **Frame**: When (on which frame) the user is working.
+* **Ping**: user's connection delay in milliseconds
+
+.. figure:: img/quickstart_users.png
+   :align: center
+
+   Online user panel
+
+By selecting a user in the list you'll have access to different 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 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                                                                        |
@@ -100,12 +319,141 @@ 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                                     |
 +---------------------------------------+-------------------+------------------------------------------------------------------------------------+
 
+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
+
+**IPC Port** is the port used for Inter Process Communication. This port is used 
+by the multi-user subprocesses to communicate with each other. If different instances
+of multi-user are using the same IPC port, this will create conflict !
+
+.. note::
+   You only need to modify this setting if you need to launch multiple clients from the same
+   computer (or if you try to host and join from the same computer). To resolve this, you simply need to enter a different
+   **IPC port** for each blender instance.
+
+**Timeout (in milliseconds)** is the maximum ping authorized before auto-disconnecting.
+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                |
++-----------+-----------------------------------------------+

docs/getting_started/troubleshooting.rst

@@ -0,0 +1,19 @@
+.. _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 <https://discord.gg/aBPvGws>`_ to chat, seek help and contribute.

docs/index.rst

@@ -18,6 +18,11 @@ Main Features
 - Datablocks right managment
 - Tested under Windows 
 
+Community
+=========
+
+A `discord server <https://discord.gg/aBPvGws>`_ have been created to provide help for new users and 
+organize collaborative creation sessions.
 
 Status
 ======
@@ -43,6 +48,8 @@ Documentation is organized into the following sections:
     
     getting_started/install
     getting_started/quickstart
+    getting_started/glossary
+    getting_started/troubleshooting
 
 .. toctree::
    :maxdepth: 1

docs/tutorials/hosting_guide.rst

@@ -1,47 +1,731 @@
-================
-Advanced hosting
-================
+.. _internet-guide:
 
-This tutorial aims to guide you to host a collaborative Session on internet.
-
-.. note::
-    This tutorial will change soon with the new dedicated server. 
-
-
-The multi-user network architecture is based on a clients-server model. The communication protocol use four ports to communicate with client:
-
-* Commands: command transmission (such as **snapshots**, **change_rights**, etc.)
-* Subscriber: pull data
-* Publisher: push data 
-* TTL (time to leave): used to ping each clients
+=======================
+Hosting on the internet
+=======================
 
 .. warning::
-    Until now, those communications are not encrypted but are planned to be in a mid-term future (`Status <https://gitlab.com/slumber/multi-user/issues/62>`_).
+    Until now, those communications are not encrypted but are planned to be in a mid-term future (`status <https://gitlab.com/slumber/multi-user/issues/62>`_).
 
-To know which ports will be used, you just have to read the port in your preference.
+This tutorial aims to guide you toward hosting a collaborative multi-user session on the internet.
+Hosting a session can be achieved in several ways:
 
-.. image:: img/hosting_guide_port.png
+- :ref:`host-blender`: hosting a session directly from the blender add-on panel.
+- :ref:`host-dedicated`: hosting a session directly from the command line interface on a computer without blender.
+- :ref:`host-cloud`: hosting a session on a dedicated cloud server such as Google Cloud's free tier.
+
+
+.. _host-blender:
+
+--------------------
+From blender
+--------------------
+By default your router doesn't allow anyone to share you connection.
+In order grant the server access to people from internet you have two main option:
+
+* The :ref:`connection-sharing`: the easiest way.
+* The :ref:`port-forwarding`: this way is the most unsecure. If you have no networking knowledge, you should definitely follow :ref:`connection-sharing`.
+
+.. _connection-sharing:
+
+Using a connection sharing solution
+-----------------------------------
+
+You can either follow `Pierre Schiller's <https://www.youtube.com/c/activemotionpictures/featured>`_ excellent video tutorial or jump to the `text tutorial <zt-installation_>`_.
+
+.. raw:: html
+
+    <p>
+    <iframe width="560" height="315" src="https://www.youtube.com/embed/xV4R5AukkVw" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+    </p>
+
+
+
+
+Many third party software like `ZEROTIER <https://www.zerotier.com/download/>`_ (Free) or `HAMACHI <https://vpn.net/>`_ (Free until 5 users) allow you to share your private network with other people.
+For the example I'm gonna use ZeroTier because it's free and open source.
+
+.. _zt-installation:
+
+1. Installation
+^^^^^^^^^^^^^^^
+
+Let's start by downloading and installing ZeroTier:
+https://www.zerotier.com/download/
+
+Once installed, launch it.
+
+2. Network creation
+^^^^^^^^^^^^^^^^^^^
+
+To create a ZeroTier private network you need to register a ZeroTier account `on my.zerotier.com <https://my.zerotier.com/login>`_
+(click on **login** then register on the bottom)
+
+Once you account it activated, you can connect to `my.zerotier.com <https://my.zerotier.com/login>`_.
+Head up to the **Network** section (highlighted in red in the image below).
+
+.. figure:: img/hosting_guide_head_network.png
+    :align: center
+    :width: 450px
+
+    ZeroTier user homepage
+
+Hit 'Create a network'(see image below) and go to the network settings.
+
+.. figure:: img/hosting_guide_create_network.png
+    :align: center
+    :width: 450px
+
+    Network page
+
+Now that the network is created, let's configure it.
+
+In the Settings section(see image below), you can change the network name to what you want.
+Make sure that the field **Access Control** is set to **PRIVATE**.
+
+.. hint::
+    If you set the Access Control to PUBLIC, anyone will be able to join without
+    your confirmation.  It is easier to set up but less secure. 
+
+.. figure:: img/hosting_guide_network_settings.png
+    :align: center
+    :width: 450px
+
+    Network settings
+
+That's all for the network setup !
+Now let's connect everyone.
+
+.. _network-authorization:
+
+3. Network authorization
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since your ZeroTier network is Private, you will need to authorize each new user
+to connect to it.
+For each user you want to add, do the following step:
+
+1. Get the client **ZeroTier id** by right clicking on the ZeroTier tray icon and click on the `Node ID`, it will copy it.
+
+.. figure:: img/hosting_guide_get_node.png
+    :align: center
+    :width: 450px
+
+    Get the ZeroTier client id
+
+2. Go to the network settings in the Member section and paste the Node ID into the Manually Add Member field.
+
+.. figure:: img/hosting_guide_add_node.png
+    :align: center
+    :width: 450px
+
+    Add the client to network-authorized users
+
+4. Network connection
+^^^^^^^^^^^^^^^^^^^^^
+
+To connect to the ZeroTier network, get the network id from the network settings (see image).
+
+.. figure:: img/hosting_guide_get_id.png
+    :align: center
+    :width: 450px
+
+Now we are ready to join the network !
+Right click on the ZeroTier tray icon and select **Join Network** ! 
+
+.. figure:: img/hosting_guide_join_network.png
+    :align: center
+    :width: 450px
+
+.. figure:: img/hosting_guide_join.png
+    :align: center
+
+    Joining the network
+ 
+Past the network id and check ``Allow Managed`` then click on join !
+You should be connected to the network.
+
+Let's check the connection status. Right click on the tray icon and click on **Show Networks...**.
+
+.. figure:: img/hosting_guide_show_network.png
+    :align: center
+    :width: 450px
+
+    Show network status
+
+.. figure:: img/hosting_guide_network_status.png
+    :align: center
+
+    Network status.
+
+The network status must be **OK** for each user(like in the picture above) otherwise it means that you are not connected to the network.
+If you see something like **ACCESS_DENIED**, it means that you were not authorized to join the network. Please check the section :ref:`network-authorization`
+
+This is it for the ZeroTier network setup. Now everything should be setup to use the multi-user add-on over internet ! You can now follow the :ref:`quickstart` guide to start using the multi-user add-on !
+
+.. _port-forwarding:
+
+Using port-forwarding
+---------------------
+
+The port forwarding method consists of configuring your network router to deny most traffic with a firewall, but to then allow particular internet traffic (like a multiuser connection) through the firewall on specified ports.
+
+In order to know which ports are used by the add-on, please check the :ref:`port-setup` section.
+To set up port forwarding for each port you can follow this `guide <https://www.wikihow.com/Set-Up-Port-Forwarding-on-a-Router>`_ for example.
+
+Once you have set up the network you can follow the :ref:`quickstart` guide to begin using the multi-user add-on !
+
+.. _host-dedicated:
+
+--------------------------
+From the dedicated server
+--------------------------
+
+.. warning::
+    The dedicated server is developed to run directly on an internet server (like a VPS (Virtual Private Server)). You can also run it at home on a LAN but for internet hosting you need to follow the :ref:`port-forwarding` setup first. Please see :ref:`host-cloud` for a detailed walkthrough of cloud hosting using Google Cloud.
+
+The dedicated server allows you to host a session with simplicity from any location.
+It was developed to improve internet hosting performance (for example poor latency).
+
+The dedicated server can be run in two ways:
+
+- :ref:`cmd-line`
+- :ref:`docker`
+
+.. Note:: There are shell scripts to conveniently start a dedicated server via either of these approaches available in the gitlab repository. See section: :ref:`serverstartscripts`
+
+.. _cmd-line:
+
+Using a regular command line
+----------------------------
+
+You can run the dedicated server on any platform by following these steps:
+
+1. Firstly, download and intall python 3 (3.6 or above).
+2. Install the latest version of the replication library:
+
+    .. code-block:: bash
+
+        python -m pip install replication==0.1.13
+
+4. Launch the server with:
+
+    .. code-block:: bash
+
+        replication.server
+
+.. hint::
+    You can also specify a custom **port** (-p), **timeout** (-t), **admin password** (-pwd), **log level (ERROR, WARNING, INFO or DEBUG)** (-l) and **log file** (-lf) with the following optional arguments
+
+    .. code-block:: bash
+
+        replication.server -p 5555 -pwd admin -t 5000 -l INFO -lf server.log
+
+Here, for example, a server is instantiated on port 5555, with password 'admin', a 5 second timeout, and logging enabled.
+
+As soon as the dedicated server is running, you can connect to it from blender by following :ref:`how-to-join`.
+
+
+.. hint::
+    Some server commands are available to enable administrators to manage a multi-user session. Check :ref:`dedicated-management` to learn more.
+
+
+.. _docker:
+
+Using a pre-configured image on docker engine
+---------------------------------------------
+
+Launching the dedicated server from a docker server is simple as running:
+
+.. code-block:: bash
+
+    docker run -d \
+        -p 5555-5560:5555-5560 \
+        -e port=5555 \
+        -e log_level=DEBUG \
+        -e password=admin \
+        -e timeout=5000 \
+        registry.gitlab.com/slumber/multi-user/multi-user-server:latest
+
+Please use the :latest tag, or otherwise use the URL of the most recent container available in the `multi-user container registry <https://gitlab.com/slumber/multi-user/container_registry/1174180>`_. As soon as the dedicated server is running, you can connect to it from blender by following :ref:`how-to-join`.
+
+You can check that your container is running, and find its ID and name with:
+
+.. code-block:: bash
+
+    docker ps
+
+.. _docker-logs:
+
+Viewing logs in a docker container
+----------------------------------
+
+Logs for the server running in a docker container can be accessed by outputting the container logs to a log file. First, you'll need to know your container ID, which you can find by running:
+
+.. code-block:: bash
+
+    docker ps
+
+Then, output the container logs to a file:
+
+.. code-block:: bash
+
+    docker logs your-container-id >& dockerserver.log
+
+.. Note:: If using WSL2 on Windows 10 (Windows Subsystem for Linux), it is preferable to run a dedicated server via regular command line approach (or the associated startup script) from within Windows - docker desktop for windows 10 usually uses the WSL2 backend where it is available.
+
+.. This may not be true. Need to write up how to locally start a docker container from WSL2
+
+
+Downloading logs from a docker container on a cloud-hosted server
+-----------------------------------------------------------------
+
+If you'd like to pull the log files from a cloud-hosted server to submit to a developer for review, a simple process using SSH and SCP is as follows:
+
+First SSH into your instance. You can either open the `VM Instances console <https://console.cloud.google.com/compute/instances>`_ and use the browser terminal provided by Google Cloud (I had the best luck using the Google Chrome browser)... or you can see `here <https://cloud.google.com/compute/docs/instances/connecting-advanced#thirdpartytools>`_ for how to set up your instance for SSH access from your local terminal.
+
+If using SSH from your terminal, first generate SSH keys (setting their access permissions to e.g. chmod 400 level whereby only the user has permissions) and submit the public key to the cloud-hosted VM instance, storing the private key on your local machine.
+Then, SSH into your cloud server from your local terminal, with the following command:
+
+.. code-block:: bash
+
+    ssh -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP_ADDRESS
+
+Use the private key which corresponds to the public key you uploaded, and the username associated with that key (visible in the Google Cloud console for your VM Instance). Use the external IP address for the server, available from the `VM Instances console <https://console.cloud.google.com/compute/instances>`_
+e.g.
+
+.. code-block:: bash
+
+    ssh -i ~/.ssh/id_rsa user@xxx.xxx.xxx.xxx
+
+Once you've connected to the server's secure shell, you can generate a log file from the docker container running the replication server. First, you'll need to know your container ID, which you can find by running:
+
+.. code-block:: bash
+
+    docker ps
+
+If you're cloud-hosting with e.g. Google Cloud, your container will be the one associated with the `registry address <https://gitlab.com/slumber/multi-user/container_registry/1174180>`_ where your Docker image was located. e.g. registry.gitlab.com/slumber/multi-user/multi-user-server:latest
+
+To view the docker container logs, run:
+
+.. code-block:: bash
+
+    docker logs your-container-name
+
+OR
+
+.. code-block:: bash
+
+    docker logs your-container-id
+
+To save the output to a file, run:
+
+.. code-block:: bash
+
+    docker logs your-container-id >& dockerserver.log
+
+Now that the server logs are available in a file, we can disconnect from the secure shell (SSH), and then copy the file to the local machine using SCP. In your local terminal, execute the following:
+
+.. code-block:: bash
+
+    scp -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP_ADDRESS:"dockerserver.log" LOCAL_PATH_TO_COPY_FILE_TO
+
+e.g.
+
+.. code-block:: bash
+
+    scp -i ~/.ssh/id_rsa user@xxx.xxx.xxx.xxx:"dockerserver.log" .
+
+This copies the file dockerserver.log generated in the previous step to the current directory on the local machine. From there, you can send it to the multi-user maintainers for review.
+
+
+.. Note:: See these `notes <https://cloud.google.com/compute/docs/containers/deploying-containers?_ga=2.113663175.-1396941296.1606125558#viewing_container_logs>`_ for how to check server logs on Google Cloud using other tools.
+
+
+.. _serverstartscripts:
+
+Server startup scripts
+----------------------
+
+Convenient scripts are available in the Gitlab repository: https://gitlab.com/slumber/multi-user/scripts/startup_scripts/
+
+Simply run the relevant script in a shell on the host machine to start a server with one line of code via replication directly or via a docker container. Choose between the two methods:
+
+    .. code-block:: bash
+
+        ./start-server.sh
+
+or
+
+    .. code-block:: bash
+
+        ./run-dockerfile.sh
+
+.. hint::
+    Once your server is up and running, some commands are available to manage the session :ref:`dedicated-management`
+
+.. _dedicated-management:
+
+Dedicated server management
+---------------------------
+
+Here is the list of available commands from the dedicated server:
+
+- ``help`` or ``?``: Show all commands. Or, use ``help <command>`` to learn about another command
+- ``exit`` or ``Ctrl+C`` : Stop the server.
+- ``kick username``: kick the provided user.
+- ``users``: list all online users.
+
+Also, see :ref:`how-to-manage` for more details on managing a server.
+
+.. _cloud-dockermanage:
+
+Managing a docker server from the command line
+----------------------------------------------
+If you want to be able to manage a server running within a docker container, open the terminal on the host machine (or SSH in, if you are using cloud hosting), and then run 
+
+.. code-block:: bash
+
+    docker ps
+    
+to find your container id, and then
+
+.. code-block:: bash
+
+    docker attach your-container-id
+    
+to attach to the STDOUT from the container. There, you can issue the server management commands detailed in :ref:`dedicated-management`. Type ``?`` and hit return/enter to see the available commands. Also, see :ref:`how-to-manage` for more details on managing a server.
+
+.. _port-setup:
+
+----------
+Port setup
+----------
+
+The multi-user network architecture is based on a client-server model. The communication protocol uses four ports to communicate with clients:
+
+* Commands: command transmission (such as **snapshots**, **change_rights**, etc.) [user-nominated port]
+* Subscriber : pull data [Commands port + 1]
+* Publisher : push data [Commands port + 2]
+* TTL (time to leave) : used to ping each client [Commands port + 3]
+
+To know which ports will be used, you just have to read the port in your preferences.
+
+.. figure:: img/hosting_guide_port.png
     :align: center
     :alt: Port
+    :width: 200px
 
-In the picture below we have setup our port to **5555** so it will be:
+    Port in host settings
 
-* Commands: 5555 (**5555** +0)
-* Subscriber: 5556 (**5555** +1)
-* Publisher: 5557 (**5555** +2)
-* TTL: 5558 (**5555** +3)
+In the picture below we have setup our port to **5555** so the four ports will be:
 
-Now that we know which port are needed to communicate we need to allow other computer to communicate with our one. 
-By default your router shall block those ports. In order grant server access to people from internet you have multiple options:
+* Commands: **5555** (5555)
+* Subscriber: **5556** (5555 +1)
+* Publisher: **5557** (5555 +2)
+* TTL: **5558** (5555 +3)
 
-1. Simple: use a third party software like `HAMACHI <https://vpn.net/>`_ (Free until 5 users) or `ZEROTIER <https://www.zerotier.com/download/>`_ to handle network sharing.
+Those four ports need to be accessible from the client otherwise multi-user won't work at all !
 
-2. Harder: Setup a VPN server and allow distant user to connect to your VPN.
+.. _host-cloud:
 
-3. **Not secure** but simple: Setup port forwarding for each ports (for example 5555,5556,5557 and 5558 in our case). You can follow this `guide <https://www.wikihow.com/Set-Up-Port-Forwarding-on-a-Router>`_ for example.
+-------------------------
+Cloud Hosting Walkthrough
+-------------------------
 
-Once you have setup the network, you can run **HOST** in order to start the server. Then other users could join your session in the regular way.
+The following is a walkthrough for how to set up a multi-user dedicated server instance on a cloud hosting provider - in this case, `Google Cloud <https://www.cloud.google.com>`_. Google Cloud is a powerful hosting service with a worldwide network of servers. It offers a free trial which provides free cloud hosting for 90 days, and then a free tier which runs indefinitely thereafter, so long as you stay within the `usage limits <https://cloud.google.com/free/docs/gcp-free-tier#free-tier-usage-limits>`_. ^^Thanks to community member @NotFood for the tip!
+
+Cloud hosting is a little more complicated to set up, but it can be valuable if you are trying to host a session with multiple friends scattered about planet earth. This can resolve issues with data replication or slowdowns due to poor latency of some users (high ping). This guide may seem technical, but if you follow the steps, you should be able to succeed in hosting an internet server to co-create with other multi-user creators around the world.
+
+Setup Process
+-------------
+
+1. Sign Up for Google Cloud
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let's start by activating an account with Google Cloud. Go to https://www.cloud.google.com and click 'Get Started For Free'
+
+.. figure:: img/hosting_guide_gcloud_1.jpg
+    :align: center
+    :width: 450px
+
+Google will ask you to login/signup, and to set up a billing account (Don't worry. It will not be charged unless you explicitly enable billing and then run over your `free credit allowance <https://cloud.google.com/free/docs/gcp-free-tier>`_). You will need to choose a billing country (relevant for `tax purposes <https://cloud.google.com/billing/docs/resources/vat-overview>`_). You will choose your server location at a later step.
+
+2. Enable Billing and Compute Engine API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From here on, we will mostly stick to the instructions provided `here <https://cloud.google.com/compute/docs/quickstart-linux>`_. Nevertheless, the instructions for multi-user specifically are as follows.
+
+In order to set up a Virtual Machine (VM) to host your server, you will need to enable the billing account which was created during your signup process. From your `console <https://console.cloud.google.com/getting-started>`_, click on 'Go to Checklist' and then 'Create a Billing Account', following the prompts to choose the billing account that was created for you upon signup.
+
+.. figure:: img/hosting_guide_gcloud_2.jpg
+    :align: center
+    :width: 300px
+
+.. figure:: img/hosting_guide_gcloud_3.jpg
+    :align: center
+    :width: 300px
+
+.. figure:: img/hosting_guide_gcloud_4.jpg
+    :align: center
+    :width: 300px
+
+.. figure:: img/hosting_guide_gcloud_5.jpg
+    :align: center
+    :width: 300px
+
+.. figure:: img/hosting_guide_gcloud_6.jpg
+    :align: center
+    :width: 300px
+
+Now hit 'Set Account', and go back to your `console <https://console.cloud.google.com/getting-started>`_.
+
+Now enable the Compute Engine API. Click `here <https://console.cloud.google.com/apis/api/compute.googleapis.com/overview>`_ to enable.
+
+.. figure:: img/hosting_guide_gcloud_7.jpg
+    :align: center
+    :width: 300px
+
+3. Create a Linux Virtual Machine Instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Continue following the `instructions <https://cloud.google.com/compute/docs/quickstart-linux#create_a_virtual_machine_instance>`_ to create a VM instance. However, once you've finished step 2 of 'Create a virtual machine instance', use the settings and steps for multi-user as follows.
+
+.. _server-location:
+
+3.1 Choose a Server Location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The most important settings which you will need to choose for your specific case are the server Region and Zone. You must choose a location which will provide the best ping for all of your fellow creators.
+
+All you need to know is that you'll probably want to choose a location near to where most of your collaborators are located. If your friends are spread out, somewhere in the middle which distributes the ping evenly to all users is best.
+
+You can use `this map <https://cloud.google.com/about/locations/>`_ to make a rough guess of the best server location, if you know your friends' locations.
+
+.. figure:: img/hosting_guide_gcloud_9.jpg
+    :align: center
+    :width: 450px
+
+A much better approach is to have your users run a ping test for Google Cloud's servers at https://www.gcping.com/
+
+Have your collaborators open this webpage from their fastest browser, and press the play button. The play button turns to a stop icon while the ping test is running. When it is complete, the play button returns. You may need to refresh your browser to get this to work. You can replay the test to add more server locations to the scan, and stop when you are satisfied that the results are consistent.
+
+Now, gather your friends' data, and work down each user's list from the top, until you find the first location which gives roughly the same ping for all users.
+
+In general, global (using load balancing) will provide the best results, but beyond that, the US Central servers e.g. IOWA generally turn out best for a globally distributed bunch of creators. When in doubt, choose between the servers offered under the `free tier <https://cloud.google.com/free/docs/gcp-free-tier>`_
+
+- Oregon: *us-west1*
+    
+- Iowa: *us-central1*
+    
+- South Carolina: *us-east1*
+
+For the following example, the server which gave the most balanced, and lowest average ping between two friends based in Europe and Australia was in Iowa. Salt Lake City would also be an excellent choice.
+
+.. figure:: img/hosting_guide_gcloud_10.jpg
+    :align: center
+    :width: 450px
+
+    Left - European User | Right - Australian User
+
+Now, input this server location in the 'Region' field for your instance, and leave the default zone which is then populated.
+
+.. Note:: You can read `here <https://cloud.google.com/solutions/best-practices-compute-engine-region-selection>`_ for a deeper understanding about how to choose a good server location.
+
+3.2 Configure the VM
+^^^^^^^^^^^^^^^^^^^^
+
+You can deploy the replication server to your VM in either of the ways mentioned at :ref:`host-dedicated`. That is, you can set it up :ref:`cmd-line` or :ref:`docker`. We will go through both options in this walkthrough. See :ref:`container_v_direct` for more details on how to choose. Deploying a container is the recommended approach.
+
+.. _cloud-container:
+
+Option 1 - Deploy a container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are familiar with Docker, you'll appreciate that it makes life a little simpler for us. While configuring your instance, you can check **Deploy a container to this VM instance** and copy in the URL of the latest docker image available from the `multi-user container registry <https://gitlab.com/slumber/multi-user/container_registry/1174180>`_ to the *Container image* field, or use the tag ``:latest``
+
+.. figure:: img/hosting_guide_gcloud_8b.jpg
+    :align: center
+    :width: 450px
+    
+    Your configuration with Docker should look like this
+
+Make sure to choose the amount of memory you'd like your server to be able to handle (how much memory does your blender scene require?). In this example, I've chosen 4GB of RAM.
+
+Click on **Advanced container options** and turn on *Allocate a buffer for STDIN* and *Allocate a pseudo-TTY* just in case you want to run an interactive shell in your container.
+
+.. _cloud-optional-parameters:
+
+Optional server parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default Docker image essentially runs the equivalent of:
+
+    .. code-block:: bash
+
+        replication.server -pwd admin -p 5555 -t 5000 -l DEBUG -lf multiuser_server.log
+
+This means the server will be launched with 'admin' as the administrator password, run on ports 5555:5558, use a timeout of 5 seconds, verbose 'DEBUG' log level, and with log files written to 'multiuser_server.log'. See :ref:`cmd-line` for a description of optional parameters.
+
+.. Note:: If you'd like to configure different server options from the default docker configuration, you can insert your options here by expanding 'Advanced container options' 
+
+For example, I would like to launch my server with a different administrator password than the default, my own log filename, and a shorter 3-second (3000ms) timeout. I'll click *Add argument* under **Command arguments** and paste the following command with options into the "command arguments" field:
+
+    .. code-block:: bash
+        
+        python3 -m replication.server -pwd supersecretpassword -p 5555 -t 3000 -l DEBUG -lf logname.log
+
+Now, my configuration should look like this:
+
+.. figure:: img/hosting_guide_gcloud_8c.jpg
+    :align: center
+    :width: 450px
+
+The rest of the settings are now complete. Hit **Create** and your instance will go live. If you've taken this approach, you're already almost there! Skip to :ref:`cloud-firewall`.
+
+.. hint:: You can find further information on configuration options `here <https://cloud.google.com/compute/docs/containers/configuring-options-to-run-containers>`_. Also, see these `notes <https://cloud.google.com/compute/docs/containers/deploying-containers?_ga=2.113663175.-1396941296.1606125558#viewing_container_logs>`_ for other options when deploying your server inside a container, including how to access the server's logs.
+
+.. _cloud-direct:
+
+Option 2 - Over SSH
+^^^^^^^^^^^^^^^^^^^
+
+Otherwise, we can run the dedicated server ourselves from the command-line over SSH.
+
+While creating your instance, keep the default settings mentioned in the `guide <https://cloud.google.com/compute/docs/quickstart-linux#create_a_virtual_machine_instance>`_, however at step 4, choose Debian version 10. Also, there is no need to enable HTTP so skip step 6.
+
+.. figure:: img/hosting_guide_gcloud_8a.jpg
+    :align: center
+    :width: 450px
+
+    Your configuration should look like this
+
+Make sure to choose the amount of memory you'd like your server to be able to handle (how much memory does your blender scene require?). In this example, I've chosen 4GB of RAM.
+
+Now, finally, click 'Create' to generate your Virtual Machine Instance.
+
+.. _cloud-firewall:
+
+4. Setting up Firewall and opening Ports
+----------------------------------------
+
+Now that your VM is instanced, you'll need to set up firewall rules, and open the ports required by multi-user. The documentation for VM firewalls on google cloud is `here <https://cloud.google.com/vpc/docs/using-firewalls#listing-rules-vm>`_.
+
+First, go to the dashboard showing your `VM instances <https://console.cloud.google.com/compute/instances>`_ and note the 'External IP' address for later. This is the address of your server. Then, click 'Set up Firewall Rules'.
+
+.. figure:: img/hosting_guide_gcloud_11.jpg
+    :align: center
+    :width: 450px
+
+    Note down your External IP
+
+Now you will need to create two rules. One to enable communication inbound to your server (ingress), and another to enable outbound communication from your server (egress). Click 'Create Firewall'
+
+.. figure:: img/hosting_guide_gcloud_12.jpg
+    :align: center
+    :width: 450px
+
+Now create a rule exactly as in the image below for the outbound communication (egress).
+
+.. figure:: img/hosting_guide_gcloud_13.jpg
+    :align: center
+    :width: 450px
+    
+    Egress
+
+.. Note:: If you set a different port number in :ref:`cloud-optional-parameters`, then use the ports indicated in :ref:`port-setup`
+
+And another rule exactly as in the image below for the inbound communication (ingress).
+
+.. figure:: img/hosting_guide_gcloud_14.jpg
+    :align: center
+    :width: 450px
+
+    Ingress
+
+Finally, your firewall configuration should look like this.
+
+.. figure:: img/hosting_guide_gcloud_15.jpg
+    :align: center
+    :width: 450px
+
+    Final Firewall Configuration
 
 
+5. Install Replication Server into Virtual Machine
+--------------------------------------------------
 
+.. Note:: Skip to :ref:`initialise-server` if you've opted to launch the server by deploying a container. Your server is already live!
 
+Now that we have set up our Virtual Machine instance, we can SSH into it, and install the Replication Server. Open the `VM Instances console <https://console.cloud.google.com/compute/instances>`_ once more, and SSH into your instance. It's easiest to use the browser terminal provided by Google Cloud (I had the best luck using the Google Chrome browser), but you can also see `here <https://cloud.google.com/compute/docs/instances/connecting-advanced#thirdpartytools>`_ for how to set up your instance for SSH access from your terminal.
+
+.. figure:: img/hosting_guide_gcloud_16.jpg
+    :align: center
+    :width: 450px
+
+Now, a terminal window should pop up in a new browser window looking something like this:
+
+.. figure:: img/hosting_guide_gcloud_17.jpg
+    :align: center
+    :width: 450px
+
+Remember, you had set up the VM with Debian 10. This comes with Python 3.7.3 already installed. The only dependency missing is to set up pip3. So, run:
+
+    .. code-block:: bash
+        
+        sudo apt install python3-pip
+
+.. figure:: img/hosting_guide_gcloud_18.jpg
+    :align: center
+    :width: 450px
+
+And now lets install the latest version of replication:
+
+    .. code-block:: bash
+        
+        sudo pip3 install replication==0.1.13
+
+6. Launch Replication Server on VM Instance
+-------------------------------------------
+
+We're finally ready to launch the server. Simply run:
+
+    .. code-block:: bash
+        
+        python3 -m replication.server -p 5555 -pwd admin -t 5000 -l INFO -lf server.log
+
+See :ref:`cmd-line` for a description of optional parameters
+
+And your replication server is live! It should stay running in the terminal window until you close it. Copy the external IP that you noted down earlier, available `here <https://console.cloud.google.com/networking/addresses/list>`_ and now you can open Blender and connect to your server!
+
+.. _initialise-server:
+
+7. Initialise your Server in Blender
+------------------------------------
+
+Once in Blender, make sure your multi-user addon is updated to the latest version. :ref:`update-version`. Then, follow the instructions from :ref:`how-to-join` and connect as an admin user, using the password you launched the server with. Input your external IP, and make sure you're set to JOIN the server. Then, click CONNECT.
+
+.. figure:: img/hosting_guide_gcloud_19.jpg
+    :align: center
+    :width: 200px
+
+Now as the admin user, you can choose whether to initialise the server with a preloaded scene, or an empty scene
+
+.. figure:: img/hosting_guide_gcloud_20.jpg
+    :align: center
+    :width: 200px
+
+Press okay, and now your session is live!
+
+If you made it this far, congratulations! You can now go ahead and share the external IP address with your friends and co-creators and have fun with real-time collaboration in Blender!
+
+Hopefully, your cloud server setup has improved your group's overall ping readings, and you're in for a smooth and trouble-free co-creation session.
+
+.. Note:: If you should so desire, pay attention to your credit and follow the steps `here <https://cloud.google.com/compute/docs/quickstart-linux#clean-up>`_ to close your instance at your discretion.
+
+.. _container_v_direct:
+
+Should I deploy a Docker Container or launch a server from Linux VM command-line?
+------------------------------------------------------
+
+- Directly from Linux VM - This approach gives you control over your session more easily. However, your server may time out once your SSH link to the server is interrupted (for example, if the admin's computer goes to sleep).
+- Deploy a Docker Container - This is the recommended approach. This approach is better for leaving a session running without supervision. It can however be more complicated to manage. Use this approach if you'd like a consistent experience with others in the multi-user community, pulling from the most up-to-date docker image maintained by @swann in the multi-user container registry.

docs/ways_to_contribute.rst

@@ -21,11 +21,11 @@ In order to help with the testing, you have several possibilities:
 - Test `development branch <https://gitlab.com/slumber/multi-user/-/branches>`_ 
 
 --------------------------
-Filling an issue on Gitlab
+Filing an issue on Gitlab
 --------------------------
 
 The `gitlab issue tracker <https://gitlab.com/slumber/multi-user/issues>`_ is used for bug report and enhancement suggestion.
-You will need a Gitlab account to be able to open a new issue there and click on "New issue" button.
+You will need a Gitlab account to be able to open a new issue there and click on "New issue" button in the main multi-user project.
 
 Here are some useful information you should provide in a bug report:
 
@@ -35,8 +35,77 @@ Here are some useful information you should provide in a bug report:
 Contributing code
 =================
 
-1. Fork it (https://gitlab.com/yourname/yourproject/fork)
-2. Create your feature branch (git checkout -b feature/fooBar)
-3. Commit your changes (git commit -am 'Add some fooBar')
-4. Push to the branch (git push origin feature/fooBar)
-5. Create a new Pull Request
+In general, this project follows the `Gitflow Workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_. It may help to understand that there are three different repositories - the upstream (main multi-user project repository, designated in git by 'upstream'), remote (forked repository, designated in git by 'origin'), and the local repository on your machine.
+The following example suggests how to contribute a feature.
+
+1. Fork the project into a new repository:
+    https://gitlab.com/yourname/multi-user
+
+2. Clone the new repository locally:
+    .. code-block:: bash
+
+        git clone https://gitlab.com/yourname/multi-user.git
+
+3. Keep your fork in sync with the main repository by setting up the upstream pointer once. cd into your git repo and then run:
+    .. code-block:: bash
+    
+        git remote add upstream https://gitlab.com/slumber/multi-user.git
+
+4. Now, locally check out the develop branch, upon which to base your new feature branch:
+    .. code-block:: bash
+
+        git checkout develop
+
+5. Fetch any changes from the main upstream repository into your fork (especially if some time has passed since forking):
+    .. code-block:: bash
+
+        git fetch upstream
+    
+    'Fetch' downloads objects and refs from the repository, but doesn’t apply them to the branch we are working on. We want to apply the updates to the branch we will work from, which we checked out in step 4. 
+
+6. Let's merge any recent changes from the remote upstream (original repository's) 'develop' branch into our local 'develop' branch:
+    .. code-block:: bash
+
+        git merge upstream/develop
+
+7. Update your forked repository's remote 'develop' branch with the fetched changes, just to keep things tidy. Make sure you haven't committed any local changes in the interim:
+    .. code-block:: bash
+
+        git push origin develop
+
+8. Locally create your own new feature branch from the develop branch, using the syntax:
+    .. code-block:: bash
+
+        git checkout -b feature/yourfeaturename
+
+    ...where 'feature/' designates a feature branch, and 'yourfeaturename' is a name of your choosing
+
+9. Add and commit your changes, including a commit message:
+    .. code-block:: bash
+
+        git commit -am 'Add fooBar'
+
+10. Push committed changes to the remote copy of your new feature branch which will be created in this step:
+    
+    .. code-block:: bash
+
+        git push -u origin feature/yourfeaturename
+
+    If it's been some time since performing steps 4 through 7, make sure to checkout 'develop' again and pull the latest changes from upstream before checking out and creating feature/yourfeaturename and pushing changes. Alternatively, checkout 'feature/yourfeaturename' and simply run:
+    
+    .. code-block:: bash
+
+        git rebase upstream/develop
+
+    and your staged commits will be merged along with the changes. More information on `rebasing here <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>`_
+
+.. Hint:: -u option sets up your locally created new branch to follow a remote branch which is now created with the same name on your remote repository.
+
+11. Finally, create a new Pull/Merge Request on Gitlab to merge the remote version of this new branch with commited updates, back into the upstream 'develop' branch, finalising the integration of the new feature.
+    Make sure to set the target branch to 'develop' for features and 'master' for hotfixes. Also, include any milestones or labels, and assignees that may be relevant. By default, the Merge option to 'delete source branch when merge request is activated' will be checked.
+
+12. Thanks for contributing!
+
+.. Note:: For hotfixes, replace 'feature/' with 'hotfix/' and base the new branch off the parent 'master' branch instead of 'develop' branch. Make sure to checkout 'master' before running step 8
+.. Note:: Let's follow the Atlassian `Gitflow Workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_, except for one main difference - submitting a pull request rather than merging by ourselves.
+.. Note:: See `here <https://philna.sh/blog/2018/08/21/git-commands-to-keep-a-fork-up-to-date/>`_ or `here <https://stefanbauer.me/articles/how-to-keep-your-git-fork-up-to-date>`_ for instructions on how to keep a fork up to date.

multi_user/__init__.py

@@ -1,12 +1,31 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 bl_info = {
     "name": "Multi-User",
     "author": "Swann Martinez",
-    "version": (0, 0, 2),
+    "version": (0, 3, 0),
     "description": "Enable real-time collaborative workflow inside blender",
-    "blender": (2, 80, 0),
+    "blender": (2, 82, 0),
     "location": "3D View > Sidebar > Multi-User tab",
     "warning": "Unstable addon, use it at your own risks",
     "category": "Collaboration",
+    "doc_url": "https://multi-user.readthedocs.io/en/develop/index.html",
     "wiki_url": "https://multi-user.readthedocs.io/en/develop/index.html",
     "tracker_url": "https://gitlab.com/slumber/multi-user/issues",
     "support": "COMMUNITY"
@@ -21,282 +40,74 @@ import sys
 import bpy
 from bpy.app.handlers import persistent
 
-from . import environment, utils, presence
-from .libs.replication.replication.constants import  RP_COMMON
+from . import environment
 
 
-# TODO: remove dependency as soon as replication will be installed as a module
 DEPENDENCIES = {
-    ("zmq","zmq"),
-    ("msgpack","msgpack"),
-    ("yaml","pyyaml"),
-    ("jsondiff","jsondiff")
+    ("replication", '0.1.26'),
 }
 
 
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.WARNING)
-
-#TODO: refactor config 
-# UTILITY FUNCTIONS
-def generate_supported_types():
-    stype_dict = {'supported_types':{}}
-    for type in bl_types.types_to_register():
-        type_module = getattr(bl_types, type)
-        type_impl_name = "Bl{}".format(type.split('_')[1].capitalize())
-        type_module_class = getattr(type_module, type_impl_name)
-
-        props = {}
-        props['bl_delay_refresh']=type_module_class.bl_delay_refresh
-        props['bl_delay_apply']=type_module_class.bl_delay_apply
-        props['use_as_filter'] = False
-        props['icon'] = type_module_class.bl_icon
-        props['auto_push']=type_module_class.bl_automatic_push
-        props['bl_name']=type_module_class.bl_id
-
-        stype_dict['supported_types'][type_impl_name] = props
-
-    return stype_dict
-
-
-def client_list_callback(scene, context):
-    from . import operators
-    
-    items = [(RP_COMMON, RP_COMMON, "")]
-
-    username = bpy.context.window_manager.session.username
-    cli = operators.client
-    if cli:
-        client_ids = cli.online_users.keys()
-        for id in client_ids:
-                name_desc = id
-                if id == username:
-                    name_desc += " (self)"
-
-                items.append((id, name_desc, ""))
-
-    return items
-
-
-def randomColor():
-    r = random.random()
-    v = random.random()
-    b = random.random()
-    return [r, v, b]
-
-class ReplicatedDatablock(bpy.types.PropertyGroup):
-    '''name = StringProperty() '''
-    type_name: bpy.props.StringProperty()
-    bl_name: bpy.props.StringProperty()
-    bl_delay_refresh: bpy.props.FloatProperty()
-    bl_delay_apply: bpy.props.FloatProperty()
-    use_as_filter: bpy.props.BoolProperty(default=True)
-    auto_push: bpy.props.BoolProperty(default=True)
-    icon: bpy.props.StringProperty()
-
-class SessionUser(bpy.types.PropertyGroup):
-    """Session User
-
-    Blender user information property 
-    """
-    username: bpy.props.StringProperty(name="username")
-    current_frame: bpy.props.IntProperty(name="current_frame")
-
-
-class SessionProps(bpy.types.PropertyGroup):
-    username: bpy.props.StringProperty(
-        name="Username",
-        default="user_{}".format(utils.random_string_digits())
-    )
-    ip: bpy.props.StringProperty(
-        name="ip",
-        description='Distant host ip',
-        default="127.0.0.1"
-        )
-    user_uuid: bpy.props.StringProperty(
-        name="user_uuid",
-        default="None"
-    )
-    port: bpy.props.IntProperty(
-        name="port",
-        description='Distant host port',
-        default=5555
-        )
-    ipc_port: bpy.props.IntProperty(
-        name="ipc_port",
-        description='internal ttl port(only usefull for multiple local instances)',
-        default=5561
-        )
-    is_admin: bpy.props.BoolProperty(
-        name="is_admin",
-        default=False
-        )
-    start_empty: bpy.props.BoolProperty(
-        name="start_empty",
-        default=True
-        )
-    session_mode: bpy.props.EnumProperty(
-        name='session_mode',
-        description='session mode',
-        items={
-            ('HOST', 'hosting', 'host a session'),
-            ('CONNECT', 'connexion', 'connect to a session')},
-        default='HOST')
-    right_strategy: bpy.props.EnumProperty(
-        name='right_strategy',
-        description='right strategy',
-        items={
-            ('STRICT', 'strict', 'strict right repartition'),
-            ('COMMON', 'common', 'relaxed right repartition')},
-        default='COMMON')
-    client_color: bpy.props.FloatVectorProperty(
-        name="client_instance_color",
-        subtype='COLOR',
-        default=randomColor())
-    clients: bpy.props.EnumProperty(
-        name="clients",
-        description="client enum",
-        items=client_list_callback)
-    enable_presence: bpy.props.BoolProperty(
-        name="Presence overlay",
-        description='Enable overlay drawing module',
-        default=True,
-        update=presence.update_presence
-        )
-    presence_show_selected: bpy.props.BoolProperty(
-        name="Show selected objects",
-        description='Enable selection overlay ',
-        default=True,
-        update=presence.update_overlay_settings
-    )
-    presence_show_user: bpy.props.BoolProperty(
-        name="Show users",
-        description='Enable user overlay ',
-        default=True,
-        update=presence.update_overlay_settings
-        )
-    supported_datablock: bpy.props.CollectionProperty(
-        type=ReplicatedDatablock,
-        )
-    session_filter: bpy.props.CollectionProperty(
-        type=ReplicatedDatablock,
-    )
-    filter_owned: bpy.props.BoolProperty(
-        name="filter_owned",
-        description='Show only owned datablocks',
-        default=True
-    )
-    user_snap_running: bpy.props.BoolProperty(
-        default=False
-    )
-    time_snap_running: bpy.props.BoolProperty(
-        default=False
-    )
-
-    def load(self):
-        config = environment.load_config()
-        if "username" in config.keys():
-            self.username = config["username"]
-            self.ip = config["ip"]
-            self.port = config["port"]
-            self.start_empty = config["start_empty"]
-            self.enable_presence = config["enable_presence"]
-            self.client_color = config["client_color"]
-        else:
-            logger.error("Fail to read user config")
-        
-        if len(self.supported_datablock)>0:
-            self.supported_datablock.clear()
-        if "supported_types" not in config:
-            config = generate_supported_types()
-        for datablock in config["supported_types"].keys():
-            rep_value = self.supported_datablock.add()
-            rep_value.name = datablock
-            rep_value.type_name = datablock
-
-            config_block = config["supported_types"][datablock]
-            rep_value.bl_delay_refresh = config_block['bl_delay_refresh']
-            rep_value.bl_delay_apply = config_block['bl_delay_apply']
-            rep_value.icon = config_block['icon']
-            rep_value.auto_push = config_block['auto_push']
-            rep_value.bl_name = config_block['bl_name']
-            
-    def save(self,context):
-        config = environment.load_config()
-
-        if "supported_types" not in config:
-            config = generate_supported_types()
-
-        config["username"] = self.username
-        config["ip"] = self.ip
-        config["port"] = self.port
-        config["start_empty"] = self.start_empty
-        config["enable_presence"] = self.enable_presence
-        config["client_color"] = [self.client_color.r,self.client_color.g,self.client_color.b]
-        
-        
-        for bloc in self.supported_datablock:
-            config_block = config["supported_types"][bloc.type_name]
-            config_block['bl_delay_refresh'] = bloc.bl_delay_refresh
-            config_block['bl_delay_apply'] = bloc.bl_delay_apply
-            config_block['use_as_filter'] = bloc.use_as_filter
-            config_block['icon'] = bloc.icon
-            config_block['auto_push'] = bloc.auto_push
-            config_block['bl_name'] = bloc.bl_name
-        environment.save_config(config)    
-
-
-classes = (
-    SessionUser,
-    ReplicatedDatablock,
-    SessionProps,
-
-)
-
-libs = os.path.dirname(os.path.abspath(__file__))+"\\libs\\replication\\replication"
-
-@persistent
-def load_handler(dummy):
-    import bpy
-    bpy.context.window_manager.session.load()
-
+module_error_msg = "Insufficient rights to install the multi-user \
+                dependencies, aunch blender with administrator rights."
 def register():
-    if libs not in sys.path:
-        sys.path.append(libs)
-    
-    environment.setup(DEPENDENCIES,bpy.app.binary_path_python)
+    # Setup logging policy
+    logging.basicConfig(
+        format='%(asctime)s CLIENT %(levelname)-8s %(message)s',
+        datefmt='%H:%M:%S',
+        level=logging.INFO)
 
-    from . import presence
-    from . import operators
-    from . import ui
+    try:
+        if bpy.app.version[1] >= 91:
+            python_binary_path = sys.executable
+        else:
+            python_binary_path = bpy.app.binary_path_python
 
-    for cls in classes:
-        bpy.utils.register_class(cls)
+        environment.setup(DEPENDENCIES, python_binary_path)
 
+        from . import presence
+        from . import operators
+        from . import ui
+        from . import preferences
+        from . import addon_updater_ops
+
+        preferences.register()
+        addon_updater_ops.register(bl_info)
+        presence.register()
+        operators.register()
+        ui.register()
+    except ModuleNotFoundError as e:
+        raise Exception(module_error_msg)
+        logging.error(module_error_msg)
+ 
     bpy.types.WindowManager.session = bpy.props.PointerProperty(
-        type=SessionProps)
-    bpy.types.ID.uuid = bpy.props.StringProperty(default="")
+        type=preferences.SessionProps)
+    bpy.types.ID.uuid = bpy.props.StringProperty(
+        default="",
+        options={'HIDDEN', 'SKIP_SAVE'})
     bpy.types.WindowManager.online_users = bpy.props.CollectionProperty(
-        type=SessionUser
+        type=preferences.SessionUser
     )
     bpy.types.WindowManager.user_index = bpy.props.IntProperty()
-    bpy.context.window_manager.session.load()
+    bpy.types.TOPBAR_MT_file_import.append(operators.menu_func_import)
 
-    presence.register()
-    operators.register()
-    ui.register()
-    bpy.app.handlers.load_post.append(load_handler)
 
 def unregister():
     from . import presence
     from . import operators
     from . import ui
+    from . import preferences
+    from . import addon_updater_ops
+
+    bpy.types.TOPBAR_MT_file_import.remove(operators.menu_func_import)
 
     presence.unregister()
+    addon_updater_ops.unregister()
     ui.unregister()
     operators.unregister()
+    preferences.unregister()
 
     del bpy.types.WindowManager.session
-
-    for cls in reversed(classes):
-        bpy.utils.unregister_class(cls)
+    del bpy.types.ID.uuid
+    del bpy.types.WindowManager.online_users
+    del bpy.types.WindowManager.user_index

multi_user/bl_types/__init__.py

@@ -1,3 +1,22 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+import bpy
+
 __all__ = [
     'bl_object',
     'bl_mesh',
@@ -16,11 +35,21 @@ __all__ = [
     'bl_metaball',
     'bl_lattice',
     'bl_lightprobe',
-    'bl_speaker'
+    'bl_speaker',
+    'bl_font',
+    'bl_sound',
+    'bl_file',
+    # 'bl_sequencer',
+    'bl_node_group',
+    'bl_texture',
+    "bl_particle",
 ]  # Order here defines execution order
 
+if bpy.app.version[1] >= 91:
+    __all__.append('bl_volume')
+
 from . import *
-from ..libs.replication.replication.data import ReplicatedDataFactory
+from replication.data import ReplicatedDataFactory
 
 def types_to_register():
     return __all__

multi_user/bl_types/bl_action.py

@@ -1,99 +1,166 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
 import mathutils
 import copy
+import numpy as np
+from enum import Enum
 
 from .. import utils
+from .dump_anything import (
+    Dumper, Loader, np_dump_collection, np_load_collection, remove_items_from_dict)
 from .bl_datablock import BlDatablock
 
-# WIP
+
+KEYFRAME = [
+    'amplitude',
+    'co',
+    'back',
+    'handle_left',
+    'handle_right',
+    'easing',
+    'handle_left_type',
+    'handle_right_type',
+    'type',
+    'interpolation',
+]
+
+
+def dump_fcurve(fcurve: bpy.types.FCurve, use_numpy: bool = True) -> dict:
+    """ Dump a sigle curve to a dict
+
+        :arg fcurve: fcurve to dump
+        :type fcurve: bpy.types.FCurve
+        :arg use_numpy: use numpy to eccelerate dump
+        :type use_numpy: bool
+        :return: dict
+    """
+    fcurve_data = {
+        "data_path": fcurve.data_path,
+        "dumped_array_index": fcurve.array_index,
+        "use_numpy": use_numpy
+    }
+
+    if use_numpy:
+        points = fcurve.keyframe_points
+        fcurve_data['keyframes_count'] = len(fcurve.keyframe_points)
+        fcurve_data['keyframe_points'] = np_dump_collection(points, KEYFRAME)
+
+    else:  # Legacy method
+        dumper = Dumper()
+        fcurve_data["keyframe_points"] = []
+
+        for k in fcurve.keyframe_points:
+            fcurve_data["keyframe_points"].append(
+                dumper.dump(k)
+            )
+
+    return fcurve_data
+
+
+def load_fcurve(fcurve_data, fcurve):
+    """ Load a dumped fcurve
+
+        :arg fcurve_data: a dumped fcurve
+        :type fcurve_data: dict
+        :arg fcurve: fcurve to dump
+        :type fcurve: bpy.types.FCurve
+    """
+    use_numpy = fcurve_data.get('use_numpy')
+
+    keyframe_points = fcurve.keyframe_points
+
+    # Remove all keyframe points
+    for i in range(len(keyframe_points)):
+        keyframe_points.remove(keyframe_points[0], fast=True)
+
+    if use_numpy:
+        keyframe_points.add(fcurve_data['keyframes_count'])
+        np_load_collection(
+            fcurve_data["keyframe_points"], keyframe_points, KEYFRAME)
+
+    else:
+        # paste dumped keyframes
+        for dumped_keyframe_point in fcurve_data["keyframe_points"]:
+            if dumped_keyframe_point['type'] == '':
+                dumped_keyframe_point['type'] = 'KEYFRAME'
+
+            new_kf = keyframe_points.insert(
+                dumped_keyframe_point["co"][0],
+                dumped_keyframe_point["co"][1],
+                options={'FAST', 'REPLACE'}
+            )
+
+            keycache = copy.copy(dumped_keyframe_point)
+            keycache = remove_items_from_dict(
+                keycache,
+                ["co", "handle_left", "handle_right", 'type']
+            )
+
+            loader = Loader()
+            loader.load(new_kf, keycache)
+
+            new_kf.type = dumped_keyframe_point['type']
+            new_kf.handle_left = [
+                dumped_keyframe_point["handle_left"][0],
+                dumped_keyframe_point["handle_left"][1]
+            ]
+            new_kf.handle_right = [
+                dumped_keyframe_point["handle_right"][0],
+                dumped_keyframe_point["handle_right"][1]
+            ]
+
+            fcurve.update()
+
 
 class BlAction(BlDatablock):
     bl_id = "actions"
     bl_class = bpy.types.Action
-    bl_delay_refresh = 1
-    bl_delay_apply = 1
-    bl_automatic_push = True
+    bl_check_common = False
     bl_icon = 'ACTION_TWEAK'
-    
-    def construct(self, data):
+    bl_reload_parent = False
+
+    def _construct(self, data):
         return bpy.data.actions.new(data["name"])
 
-    def load(self, data, target):
-        begin_frame = 100000
-        end_frame = -100000
-
-        for dumped_fcurve in data["fcurves"]:
-            begin_frame = min(
-                begin_frame,
-                min(
-                    [begin_frame] + [dkp["co"][0] for dkp in dumped_fcurve["keyframe_points"]]
-                )
-            )
-            end_frame = max(
-                end_frame,
-                max(
-                    [end_frame] + [dkp["co"][0] for dkp in dumped_fcurve["keyframe_points"]]
-                )
-            )
-        begin_frame = 0
-
-        loader = utils.dump_anything.Loader()
+    def _load_implementation(self, data, target):
         for dumped_fcurve in data["fcurves"]:
             dumped_data_path = dumped_fcurve["data_path"]
             dumped_array_index = dumped_fcurve["dumped_array_index"]
 
             # create fcurve if needed
-            fcurve = target.fcurves.find(dumped_data_path, index=dumped_array_index)
+            fcurve = target.fcurves.find(
+                dumped_data_path, index=dumped_array_index)
             if fcurve is None:
-                fcurve = target.fcurves.new(dumped_data_path, index=dumped_array_index)
+                fcurve = target.fcurves.new(
+                    dumped_data_path, index=dumped_array_index)
 
+            load_fcurve(dumped_fcurve, fcurve)
 
-            # remove keyframes within dumped_action range
-            for keyframe in reversed(fcurve.keyframe_points):
-                if end_frame >= (keyframe.co[0] + begin_frame ) >= begin_frame:
-                    fcurve.keyframe_points.remove(keyframe, fast=True)
+        id_root = data.get('id_root')
 
-            # paste dumped keyframes
-            for dumped_keyframe_point in dumped_fcurve["keyframe_points"]:
-                if dumped_keyframe_point['type'] == '':
-                    dumped_keyframe_point['type'] = 'KEYFRAME' 
+        if id_root:
+            target.id_root = id_root
 
-                new_kf = fcurve.keyframe_points.insert(
-                    dumped_keyframe_point["co"][0] - begin_frame,
-                    dumped_keyframe_point["co"][1],
-                    options={'FAST', 'REPLACE'}
-                )
-
-                keycache  = copy.copy(dumped_keyframe_point)
-                keycache =  utils.dump_anything.remove_items_from_dict(
-                        keycache,
-                        ["co", "handle_left", "handle_right",'type']
-                    )
-                
-                loader.load(
-                    new_kf,
-                    keycache
-                )
-
-                new_kf.type = dumped_keyframe_point['type']
-                new_kf.handle_left = [
-                    dumped_keyframe_point["handle_left"][0] - begin_frame,
-                    dumped_keyframe_point["handle_left"][1]
-                ]
-                new_kf.handle_right = [
-                    dumped_keyframe_point["handle_right"][0] - begin_frame,
-                    dumped_keyframe_point["handle_right"][1]
-                ]
-
-            # clearing (needed for blender to update well)
-            if len(fcurve.keyframe_points) == 0:
-                target.fcurves.remove(fcurve)
-        target.id_root= data['id_root']
-
-    def dump(self, pointer=None):
-        assert(pointer)
-        dumper = utils.dump_anything.Dumper()
-        dumper.exclude_filter =[
+    def _dump_implementation(self, data, instance=None):
+        dumper = Dumper()
+        dumper.exclude_filter = [
             'name_full',
             'original',
             'use_fake_user',
@@ -106,28 +173,11 @@ class BlAction(BlDatablock):
             'users'
         ]
         dumper.depth = 1
-        data =  dumper.dump(pointer)
+        data = dumper.dump(instance)
 
-        
         data["fcurves"] = []
-        dumper.depth = 2
-        for fcurve in self.pointer.fcurves:
-            fc = {
-                "data_path": fcurve.data_path,
-                "dumped_array_index": fcurve.array_index,
-                "keyframe_points": []
-            }
 
-            for k in fcurve.keyframe_points:
-                fc["keyframe_points"].append(
-                    dumper.dump(k)
-                )
-
-            data["fcurves"].append(fc)
+        for fcurve in instance.fcurves:
+            data["fcurves"].append(dump_fcurve(fcurve, use_numpy=True))
 
         return data
-
-    def is_valid(self):
-        return bpy.data.actions.get(self.data['name'])
-
-

multi_user/bl_types/bl_armature.py

@@ -1,36 +1,61 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
 import mathutils
 
-from ..libs.overrider import Overrider
-from .. import utils
-from .. import presence, operators
+
+from .dump_anything import Loader, Dumper
+from .. import presence, operators, utils
 from .bl_datablock import BlDatablock
 
-# WIP
+
+def get_roll(bone: bpy.types.Bone) -> float:
+    """ Compute the actuall roll of a pose bone
+
+        :arg pose_bone: target pose bone
+        :type pose_bone: bpy.types.PoseBone
+        :return: float
+    """
+    return bone.AxisRollFromMatrix(bone.matrix_local.to_3x3())[1]
 
 
 class BlArmature(BlDatablock):
     bl_id = "armatures"
     bl_class = bpy.types.Armature
-    bl_delay_refresh = 1
-    bl_delay_apply = 0
-    bl_automatic_push = True
+    bl_check_common = False
     bl_icon = 'ARMATURE_DATA'
-    
-    def construct(self, data):
+    bl_reload_parent = False
+
+    def _construct(self, data):
         return bpy.data.armatures.new(data["name"])
 
-    def load_implementation(self, data, target):
+    def _load_implementation(self, data, target):
         # Load parent object
         parent_object = utils.find_from_attr(
             'uuid',
             data['user'],
             bpy.data.objects
-            )
-        
+        )
+
         if parent_object is None:
             parent_object = bpy.data.objects.new(
-                data['user_name'], self.pointer)
+                data['user_name'], target)
             parent_object.uuid = data['user']
 
         is_object_in_master = (
@@ -65,10 +90,10 @@ class BlArmature(BlDatablock):
         bpy.ops.object.mode_set(mode='EDIT')
 
         for bone in data['bones']:
-            if bone not in self.pointer.edit_bones:
-                new_bone = self.pointer.edit_bones.new(bone)
+            if bone not in target.edit_bones:
+                new_bone = target.edit_bones.new(bone)
             else:
-                new_bone = self.pointer.edit_bones[bone]
+                new_bone = target.edit_bones[bone]
 
             bone_data = data['bones'].get(bone)
 
@@ -76,14 +101,16 @@ class BlArmature(BlDatablock):
             new_bone.head = bone_data['head_local']
             new_bone.tail_radius = bone_data['tail_radius']
             new_bone.head_radius = bone_data['head_radius']
-
+            new_bone.roll =  bone_data['roll']
+            
             if 'parent' in bone_data:
-                new_bone.parent = self.pointer.edit_bones[data['bones']
-                                                          [bone]['parent']]
+                new_bone.parent = target.edit_bones[data['bones']
+                                                    [bone]['parent']]
                 new_bone.use_connect = bone_data['use_connect']
 
-            utils.dump_anything.load(new_bone, bone_data)
-            
+            loader = Loader()
+            loader.load(new_bone, bone_data)
+
         if bpy.context.mode != 'OBJECT':
             bpy.ops.object.mode_set(mode='OBJECT')
         bpy.context.view_layer.objects.active = current_active_object
@@ -92,10 +119,10 @@ class BlArmature(BlDatablock):
         if 'EDIT' in current_mode:
             bpy.ops.object.mode_set(mode='EDIT')
 
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
+    def _dump_implementation(self, data, instance=None):
+        assert(instance)
 
-        dumper = utils.dump_anything.Dumper()
+        dumper = Dumper()
         dumper.depth = 4
         dumper.include_filter = [
             'bones',
@@ -106,16 +133,16 @@ class BlArmature(BlDatablock):
             'use_connect',
             'parent',
             'name',
-            'layers'
-
+            'layers',
         ]
-        data = dumper.dump(pointer)
+        data = dumper.dump(instance)
 
-        for bone in pointer.bones:
+        for bone in instance.bones:
             if bone.parent:
                 data['bones'][bone.name]['parent'] = bone.parent.name
         # get the parent Object
-        object_users = utils.get_datablock_users(pointer)[0]
+        # TODO: Use id_data instead
+        object_users = utils.get_datablock_users(instance)[0]
         data['user'] = object_users.uuid
         data['user_name'] = object_users.name
 
@@ -125,7 +152,8 @@ class BlArmature(BlDatablock):
             item.name for item in container_users if isinstance(item, bpy.types.Collection)]
         data['user_scene'] = [
             item.name for item in container_users if isinstance(item, bpy.types.Scene)]
-        return data
 
-    def is_valid(self):
-        return bpy.data.armatures.get(self.data['name'])
+        for bone in instance.bones:
+            data['bones'][bone.name]['roll'] = get_roll(bone)
+
+        return data

multi_user/bl_types/bl_camera.py

@@ -1,35 +1,68 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
 import mathutils
 
-from .. import utils
+from .dump_anything import Loader, Dumper
 from .bl_datablock import BlDatablock
 
 
 class BlCamera(BlDatablock):
     bl_id = "cameras"
     bl_class = bpy.types.Camera
-    bl_delay_refresh = 1
-    bl_delay_apply = 1
-    bl_automatic_push = True
+    bl_check_common = False
     bl_icon = 'CAMERA_DATA'
+    bl_reload_parent = False
 
-    def load(self, data, target):
-        utils.dump_anything.load(target, data)
+    def _construct(self, data):
+        return bpy.data.cameras.new(data["name"])
+
+
+    def _load_implementation(self, data, target):
+        loader = Loader()       
+        loader.load(target, data)
 
         dof_settings = data.get('dof')
         
         # DOF settings
         if dof_settings:
-            utils.dump_anything.load(target.dof, dof_settings)
+            loader.load(target.dof, dof_settings)
 
-    def construct(self, data):
-        return bpy.data.cameras.new(data["name"])
+        background_images = data.get('background_images')
 
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
+        target.background_images.clear()
+        
+        if background_images:
+            for img_name, img_data in background_images.items():
+                img_id = img_data.get('image')
+                if img_id:
+                    target_img = target.background_images.new()
+                    target_img.image = bpy.data.images[img_id]
+                    loader.load(target_img, img_data)
 
-        dumper = utils.dump_anything.Dumper()
-        dumper.depth = 2
+    def _dump_implementation(self, data, instance=None):
+        assert(instance)
+
+        # TODO: background image support
+        
+        dumper = Dumper()
+        dumper.depth = 3
         dumper.include_filter = [
             "name",
             'type',
@@ -48,9 +81,34 @@ class BlCamera(BlDatablock):
             'aperture_fstop',
             'aperture_blades',
             'aperture_rotation',
+            'ortho_scale',
             'aperture_ratio',
+            'display_size',
+            'show_limits',
+            'show_mist',
+            'show_sensor',
+            'show_name',
+            'sensor_fit',
+            'sensor_height',
+            'sensor_width',
+            'show_background_images',
+            'background_images',
+            'alpha',
+            'display_depth',
+            'frame_method',
+            'offset',
+            'rotation',
+            'scale',
+            'use_flip_x',
+            'use_flip_y',
+            'image'
         ]
-        return dumper.dump(pointer)
-
-    def is_valid(self):
-        return bpy.data.cameras.get(self.data['name'])
+        return dumper.dump(instance)
+    
+    def _resolve_deps_implementation(self):
+        deps = []
+        for background in self.instance.background_images:
+            if background.image:
+                deps.append(background.image)
+        
+        return deps

multi_user/bl_types/bl_collection.py

@@ -1,92 +1,138 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
 import mathutils
 
 from .. import utils
 from .bl_datablock import BlDatablock
+from .dump_anything import Loader, Dumper
 
 
+def dump_collection_children(collection):
+    collection_children = []
+    for child in collection.children:
+        if child not in collection_children:
+            collection_children.append(child.uuid)
+    return collection_children
+
+
+def dump_collection_objects(collection):
+    collection_objects = []
+    for object in collection.objects:
+        if object not in collection_objects:
+            collection_objects.append(object.uuid)
+
+    return collection_objects
+
+
+def load_collection_objects(dumped_objects, collection):
+    for object in dumped_objects:
+        object_ref = utils.find_from_attr('uuid', object, bpy.data.objects)
+
+        if object_ref is None:
+            continue
+        elif object_ref.name not in collection.objects.keys():
+            collection.objects.link(object_ref)
+
+    for object in collection.objects:
+        if object.uuid not in dumped_objects:
+            collection.objects.unlink(object)
+
+
+def load_collection_childrens(dumped_childrens, collection):
+    for child_collection in dumped_childrens:
+        collection_ref = utils.find_from_attr(
+            'uuid',
+            child_collection,
+            bpy.data.collections)
+
+        if collection_ref is None:
+            continue
+        if collection_ref.name not in collection.children.keys():
+            collection.children.link(collection_ref)
+
+    for child_collection in collection.children:
+        if child_collection.uuid not in dumped_childrens:
+            collection.children.unlink(child_collection)
+
+def resolve_collection_dependencies(collection):
+    deps = []
+
+    for child in collection.children:
+        deps.append(child)
+    for object in collection.objects:
+        deps.append(object)
+
+    return deps
+
 class BlCollection(BlDatablock):
     bl_id = "collections"
     bl_icon = 'FILE_FOLDER'
     bl_class = bpy.types.Collection
-    bl_delay_refresh = 1
-    bl_delay_apply = 1
-    bl_automatic_push = True
-
-    def construct(self, data):
+    bl_check_common = True
+    bl_reload_parent = False
+    
+    def _construct(self, data):
         if self.is_library:
             with bpy.data.libraries.load(filepath=bpy.data.libraries[self.data['library']].filepath, link=True) as (sourceData, targetData):
                 targetData.collections = [
                     name for name in sourceData.collections if name == self.data['name']]
-            
+
             instance = bpy.data.collections[self.data['name']]
-            instance.uuid = self.uuid
-            
+
             return instance
 
         instance = bpy.data.collections.new(data["name"])
-        instance.uuid = self.uuid
         return instance
 
-    def load(self, data, target):
-        # Load other meshes metadata
-        # dump_anything.load(target, data)
-        target.name = data["name"]
-        
-        # link objects
-        for object in data["objects"]:
-            object_ref = utils.find_from_attr('uuid', object, bpy.data.objects)
-            if object_ref and object_ref.name not in target.objects.keys():
-                target.objects.link(object_ref)
+    def _load_implementation(self, data, target):
+        loader = Loader()
+        loader.load(target, data)
 
-        for object in target.objects:
-            if object.uuid not in data["objects"]:
-                target.objects.unlink(object)
+        # Objects
+        load_collection_objects(data['objects'], target)
 
         # Link childrens
-        for collection in data["children"]:
-            collection_ref = utils.find_from_attr(
-                'uuid', collection, bpy.data.collections)
-            if collection_ref and collection_ref.name not in target.children.keys():
-                target.children.link(collection_ref)
+        load_collection_childrens(data['children'], target)
 
-        for collection in target.children:
-            if collection.uuid not in data["children"]:
-                target.children.unlink(collection)
+        # FIXME: Find a better way after the replication big refacotoring
+        # Keep other user from deleting collection object by flushing their history
+        utils.flush_history()
 
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
-        data = {}
-        data['name'] = pointer.name
+    def _dump_implementation(self, data, instance=None):
+        assert(instance)
+
+        dumper = Dumper()
+        dumper.depth = 1
+        dumper.include_filter = [
+            "name",
+            "instance_offset"
+        ]
+        data = dumper.dump(instance)
 
         # dump objects
-        collection_objects = []
-        for object in pointer.objects:
-            if object not in collection_objects:
-                collection_objects.append(object.uuid)
-
-        data['objects'] = collection_objects
+        data['objects'] = dump_collection_objects(instance)
 
         # dump children collections
-        collection_children = []
-        for child in pointer.children:
-            if child not in collection_children:
-                collection_children.append(child.uuid)
-
-        data['children'] = collection_children
+        data['children'] = dump_collection_children(instance)
 
         return data
 
-    def resolve_dependencies(self):
-        deps = []
-
-        for child in self.pointer.children:
-            deps.append(child)
-        for object in self.pointer.objects:
-            deps.append(object)
-
-        return deps
-
-    def is_valid(self):
-        return bpy.data.collections.get(self.data['name'])
-
+    def _resolve_deps_implementation(self):
+        return resolve_collection_dependencies(self.instance)

multi_user/bl_types/bl_curve.py

@@ -1,63 +1,248 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
+import bpy.types as T
 import mathutils
+import logging
 
 from .. import utils
 from .bl_datablock import BlDatablock
+from .dump_anything import (Dumper, Loader,
+                            np_load_collection,
+                            np_dump_collection)
+from .bl_datablock import get_datablock_from_uuid
+from .bl_material import dump_materials_slots, load_materials_slots
+
+SPLINE_BEZIER_POINT = [
+    # "handle_left_type",
+    # "handle_right_type",
+    "handle_left",
+    "co",
+    "handle_right",
+    "tilt",
+    "weight_softbody",
+    "radius",
+]
+
+SPLINE_POINT = [
+    "co",
+    "tilt",
+    "weight_softbody",
+    "radius",
+]
+
+CURVE_METADATA = [
+    'align_x',
+    'align_y',
+    'bevel_depth',
+    'bevel_factor_end',
+    'bevel_factor_mapping_end',
+    'bevel_factor_mapping_start',
+    'bevel_factor_start',
+    'bevel_object',
+    'bevel_resolution',
+    'body',
+    'body_format',
+    'dimensions',
+    'eval_time',
+    'extrude',
+    'family',
+    'fill_mode',
+    'follow_curve',
+    'font',
+    'font_bold',
+    'font_bold_italic',
+    'font_italic',
+    'name',
+    'offset',
+    'offset_x',
+    'offset_y',
+    'overflow',
+    'original',
+    'override_create',
+    'override_library',
+    'path_duration',
+    'render_resolution_u',
+    'render_resolution_v',
+    'resolution_u',
+    'resolution_v',
+    'shape_keys',
+    'shear',
+    'size',
+    'small_caps_scale',
+    'space_character',
+    'space_line',
+    'space_word',
+    'type',
+    'taper_object',
+    'texspace_location',
+    'texspace_size',
+    'transform',
+    'twist_mode',
+    'twist_smooth',
+    'underline_height',
+    'underline_position',
+    'use_auto_texspace',
+    'use_deform_bounds',
+    'use_fake_user',
+    'use_fill_caps',
+    'use_fill_deform',
+    'use_map_taper',
+    'use_path',
+    'use_path_follow',
+    'use_radius',
+    'use_stretch',
+]
+
+
+SPLINE_METADATA = [
+    'hide',
+    'material_index',
+    # 'order_u',
+    # 'order_v',
+    # 'point_count_u',
+    # 'point_count_v',
+    'points',
+    'radius_interpolation',
+    'resolution_u',
+    'resolution_v',
+    'tilt_interpolation',
+    'type',
+    'use_bezier_u',
+    'use_bezier_v',
+    'use_cyclic_u',
+    'use_cyclic_v',
+    'use_endpoint_u',
+    'use_endpoint_v',
+    'use_smooth',
+]
+
 
 class BlCurve(BlDatablock):
     bl_id = "curves"
     bl_class = bpy.types.Curve
-    bl_delay_refresh = 1
-    bl_delay_apply = 1
-    bl_automatic_push = True
+    bl_check_common = False
     bl_icon = 'CURVE_DATA'
+    bl_reload_parent = False
 
-    def construct(self, data):
-        return bpy.data.curves.new(data["name"], 'CURVE')
+    def _construct(self, data):
+        return bpy.data.curves.new(data["name"], data["type"])
 
-    def load(self, data, target):
-        utils.dump_anything.load(target, data)
+    def _load_implementation(self, data, target):
+        loader = Loader()
+        loader.load(target, data)
 
         target.splines.clear()
+
         # load splines
-        for spline in data['splines']:
-            new_spline = target.splines.new(data['splines'][spline]['type'])
-            utils.dump_anything.load(new_spline, data['splines'][spline])
+        for spline in data['splines'].values():
+            new_spline = target.splines.new(spline['type'])
 
             # Load curve geometry data
-            for bezier_point_index in data['splines'][spline]["bezier_points"]:
-                if bezier_point_index != 0:
-                    new_spline.bezier_points.add(1)
-                utils.dump_anything.load(
-                    new_spline.bezier_points[bezier_point_index], data['splines'][spline]["bezier_points"][bezier_point_index])
+            if new_spline.type == 'BEZIER':
+                bezier_points = new_spline.bezier_points
+                bezier_points.add(spline['bezier_points_count'])
+                np_load_collection(
+                    spline['bezier_points'],
+                    bezier_points,
+                    SPLINE_BEZIER_POINT)
 
-            for point_index in data['splines'][spline]["points"]:
-                new_spline.points.add(1)
-                utils.dump_anything.load(
-                    new_spline.points[point_index], data['splines'][spline]["points"][point_index])
+            if new_spline.type in ['POLY', 'NURBS']:
+                points = new_spline.points
+                points.add(spline['points_count'])
+                np_load_collection(spline['points'], points, SPLINE_POINT)
 
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
-        data = utils.dump_datablock(pointer, 1)
+            loader.load(new_spline, spline)
+
+            # MATERIAL SLOTS
+            src_materials = data.get('materials', None)
+            if src_materials:
+                load_materials_slots(src_materials, target.materials)
+
+    def _dump_implementation(self, data, instance=None):
+        assert(instance)
+        dumper = Dumper()
+        # Conflicting attributes
+        # TODO: remove them with the NURBS support
+        dumper.include_filter = CURVE_METADATA
+
+        dumper.exclude_filter = [
+            'users',
+            'order_u',
+            'order_v',
+            'point_count_v',
+            'point_count_u',
+            'active_textbox'
+        ]
+        if instance.use_auto_texspace:
+            dumper.exclude_filter.extend([
+                'texspace_location',
+                'texspace_size'])
+        data = dumper.dump(instance)
         data['splines'] = {}
 
-        dumper = utils.dump_anything.Dumper()
-        dumper.depth = 3
-        
-        for index,spline in enumerate(pointer.splines):
-            spline_data = {}
-            spline_data['points'] = dumper.dump(spline.points)
-            spline_data['bezier_points'] = dumper.dump(spline.bezier_points)
-            spline_data['type'] = dumper.dump(spline.type)
+        for index, spline in enumerate(instance.splines):
+            dumper.depth = 2
+            dumper.include_filter = SPLINE_METADATA
+            spline_data = dumper.dump(spline)
+
+            spline_data['points_count'] = len(spline.points)-1
+            spline_data['points'] = np_dump_collection(
+                spline.points, SPLINE_POINT)
+
+            spline_data['bezier_points_count'] = len(spline.bezier_points)-1
+            spline_data['bezier_points'] = np_dump_collection(
+                spline.bezier_points, SPLINE_BEZIER_POINT)
             data['splines'][index] = spline_data
 
-        if isinstance(pointer,'TextCurve'):
-            data['type'] = 'TEXT'
-        if isinstance(pointer,'SurfaceCurve'):
+        if isinstance(instance, T.SurfaceCurve):
             data['type'] = 'SURFACE'
-        if isinstance(pointer,'TextCurve'):
+        elif isinstance(instance, T.TextCurve):
+            data['type'] = 'FONT'
+        elif isinstance(instance, T.Curve):
             data['type'] = 'CURVE'
+
+        data['materials'] = dump_materials_slots(instance.materials)
+
         return data
 
-    def is_valid(self):
-        return bpy.data.curves.get(self.data['name'])
+    def _resolve_deps_implementation(self):
+        # TODO: resolve material
+        deps = []
+        curve = self.instance
+
+        if isinstance(curve, T.TextCurve):
+            deps.extend([
+                curve.font,
+                curve.font_bold,
+                curve.font_bold_italic,
+                curve.font_italic])
+
+        for material in self.instance.materials:
+            if material:
+                deps.append(material)
+
+        return deps
+
+    def diff(self):
+        if 'EDIT' in bpy.context.mode \
+                and not self.preferences.sync_flags.sync_during_editmode:
+            return False
+        else:
+            return super().diff()

multi_user/bl_types/bl_datablock.py

@@ -1,13 +1,51 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
+import logging
+from collections.abc import Iterable
+
 import bpy
 import mathutils
+from replication.constants import DIFF_BINARY, DIFF_JSON, UP
+from replication.data import ReplicatedDatablock
 
 from .. import utils
-from ..libs.replication.replication.data import ReplicatedDatablock
-from ..libs.replication.replication.constants import UP
-from ..libs.replication.replication.constants import DIFF_BINARY
+from .dump_anything import Dumper, Loader
+
+
+def has_action(target):
+    """ Check if the target datablock has actions
+    """
+    return (hasattr(target, 'animation_data')
+            and target.animation_data
+            and target.animation_data.action)
+
+
+def has_driver(target):
+    """ Check if the target datablock is driven
+    """
+    return (hasattr(target, 'animation_data')
+            and target.animation_data
+            and target.animation_data.drivers)
+
 
 def dump_driver(driver):
-    dumper = utils.dump_anything.Dumper()
+    dumper = Dumper()
     dumper.depth = 6
     data = dumper.dump(driver)
 
@@ -15,14 +53,15 @@ def dump_driver(driver):
 
 
 def load_driver(target_datablock, src_driver):
+    loader = Loader()
     drivers = target_datablock.animation_data.drivers
     src_driver_data = src_driver['driver']
-    new_driver = drivers.new(src_driver['data_path'])
+    new_driver = drivers.new(src_driver['data_path'], index=src_driver['array_index'])
 
     # Settings
     new_driver.driver.type = src_driver_data['type']
     new_driver.driver.expression = src_driver_data['expression']
-    utils.dump_anything.load(new_driver,  src_driver)
+    loader.load(new_driver,  src_driver)
 
     # Variables
     for src_variable in src_driver_data['variables']:
@@ -35,7 +74,7 @@ def load_driver(target_datablock, src_driver):
             src_target_data = src_var_data['targets'][src_target]
             new_var.targets[src_target].id = utils.resolve_from_id(
                 src_target_data['id'], src_target_data['id_type'])
-            utils.dump_anything.load(
+            loader.load(
                 new_var.targets[src_target],  src_target_data)
 
     # Fcurve
@@ -47,8 +86,19 @@ def load_driver(target_datablock, src_driver):
 
     for index, src_point in enumerate(src_driver['keyframe_points']):
         new_point = new_fcurve[index]
-        utils.dump_anything.load(
-            new_point, src_driver['keyframe_points'][src_point])
+        loader.load(new_point, src_driver['keyframe_points'][src_point])
+
+
+def get_datablock_from_uuid(uuid, default, ignore=[]):
+    if not uuid:
+        return default
+    for category in dir(bpy.data):
+        root = getattr(bpy.data, category)
+        if isinstance(root, Iterable) and category not in ignore:
+            for item in root:
+                if getattr(item, 'uuid', None) == uuid:
+                    return item
+    return default
 
 
 class BlDatablock(ReplicatedDatablock):
@@ -56,96 +106,86 @@ class BlDatablock(ReplicatedDatablock):
 
         bl_id :             blender internal storage identifier
         bl_class :          blender internal type
-        bl_delay_refresh :  refresh rate in second for observers
-        bl_delay_apply :    refresh rate in sec for apply
-        bl_automatic_push : boolean
         bl_icon :           type icon (blender icon name) 
+        bl_check_common:    enable check even in common rights
+        bl_reload_parent:   reload parent
     """
-    bl_id = "scenes"
+
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        pointer = kwargs.get('pointer', None)
+        instance = kwargs.get('instance', None)
+        
+        self.preferences = utils.get_preferences()
 
         # TODO: use is_library_indirect
-        self.is_library = (pointer and hasattr(pointer, 'library') and
-                           pointer.library) or \
-            (self.data and 'library' in self.data)
+        self.is_library = (instance and hasattr(instance, 'library') and
+                           instance.library) or \
+            (hasattr(self,'data') and self.data and 'library' in self.data)
 
-        if self.is_library:
-            self.load = self.load_library
-            self.dump = self.dump_library
-            self.diff = self.diff_library
-            self.resolve_dependencies = self.resolve_dependencies_library
+        if instance and hasattr(instance, 'uuid'):
+            instance.uuid = self.uuid
 
-        if self.pointer and hasattr(self.pointer, 'uuid'):
-            self.pointer.uuid = self.uuid
-        
-        self.diff_method = DIFF_BINARY
-
-    def library_apply(self):
-        """Apply stored data
-        """
-        # UP in case we want to reset our pointer data
-        self.state = UP
-
-    def bl_diff(self):
-        """Generic datablock diff"""
-        return self.pointer.name != self.data['name']
-
-    def construct_library(self, data):
-        return None
-
-    def load_library(self, data, target):
-        pass
-
-    def dump_library(self, pointer=None):
-        return utils.dump_datablock(pointer, 1)
-
-    def diff_library(self):
-        return False
-
-    def resolve_dependencies_library(self):
-        return [self.pointer.library]
-
-    def resolve(self):
-        datablock_ref = None
+    def resolve(self, construct = True):
         datablock_root = getattr(bpy.data, self.bl_id)
         datablock_ref = utils.find_from_attr('uuid', self.uuid, datablock_root)
 
-        # In case of lost uuid (ex: undo), resolve by name and reassign it
-        # TODO: avoid reference storing
         if not datablock_ref:
-            datablock_ref = getattr(
-                bpy.data, self.bl_id).get(self.data['name'])
+            try:
+                datablock_ref = datablock_root[self.data['name']]
+            except Exception:
+                pass
 
-            if datablock_ref:
-                setattr(datablock_ref, 'uuid', self.uuid)
+            if construct and not datablock_ref:
+                name = self.data.get('name')
+                logging.debug(f"Constructing {name}")
+                datablock_ref = self._construct(data=self.data)
 
-        self.pointer = datablock_ref
+        if datablock_ref is not None:
+            setattr(datablock_ref, 'uuid', self.uuid)
+            self.instance = datablock_ref
+            return True
+        else:
+            return False
+        
 
-    def dump(self, pointer=None):
+    def remove_instance(self):
+        """
+        Remove instance from blender data
+        """
+        assert(self.instance)
+
+        datablock_root = getattr(bpy.data, self.bl_id)
+        datablock_root.remove(self.instance)
+
+    def _dump(self, instance=None):
+        dumper = Dumper()
         data = {}
-        if utils.has_action(pointer):
-            dumper = utils.dump_anything.Dumper()
+        # Dump animation data
+        if has_action(instance):
+            dumper = Dumper()
             dumper.include_filter = ['action']
-            data['animation_data'] = dumper.dump(pointer.animation_data)
+            data['animation_data'] = dumper.dump(instance.animation_data)
 
-        if utils.has_driver(pointer):
+        if has_driver(instance):
             dumped_drivers = {'animation_data': {'drivers': []}}
-            for driver in pointer.animation_data.drivers:
+            for driver in instance.animation_data.drivers:
                 dumped_drivers['animation_data']['drivers'].append(
                     dump_driver(driver))
 
             data.update(dumped_drivers)
-        data.update(self.dump_implementation(data, pointer=pointer))
+
+        if self.is_library:
+            data.update(dumper.dump(instance))
+        else:
+            data.update(self._dump_implementation(data, instance=instance))
 
         return data
 
-    def dump_implementation(self, data, target):
+    def _dump_implementation(self, data, target):
         raise NotImplementedError
 
-    def load(self, data, target):
+    def _load(self, data, target):
         # Load animation data
         if 'animation_data' in data.keys():
             if target.animation_data is None:
@@ -160,19 +200,32 @@ class BlDatablock(ReplicatedDatablock):
 
             if 'action' in data['animation_data']:
                 target.animation_data.action = bpy.data.actions[data['animation_data']['action']]
+        # Remove existing animation data if there is not more to load
+        elif hasattr(target, 'animation_data') and target.animation_data:
+            target.animation_data_clear()
 
-        self.load_implementation(data, target)
+        if self.is_library:
+            return
+        else:
+            self._load_implementation(data, target)
 
-    def load_implementation(self, data, target):
+    def _load_implementation(self, data, target):
         raise NotImplementedError
 
-    def resolve_dependencies(self):
+    def resolve_deps(self):
         dependencies = []
 
-        if utils.has_action(self.pointer):
-            dependencies.append(self.pointer.animation_data.action)
+        if has_action(self.instance):
+            dependencies.append(self.instance.animation_data.action)
 
+        if not self.is_library:
+            dependencies.extend(self._resolve_deps_implementation())
+
+        logging.debug(f"{self.instance} dependencies: {dependencies}")
         return dependencies
 
+    def _resolve_deps_implementation(self):
+        return []
+
     def is_valid(self):
-        raise NotImplementedError
+        return getattr(bpy.data, self.bl_id).get(self.data['name'])

multi_user/bl_types/bl_file.py

@@ -0,0 +1,139 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import bpy
+import mathutils
+from replication.constants import DIFF_BINARY, UP
+from replication.data import ReplicatedDatablock
+
+from .. import utils
+from .dump_anything import Dumper, Loader
+
+
+def get_filepath(filename):
+    """
+    Construct the local filepath 
+    """
+    return str(Path(
+        utils.get_preferences().cache_directory,
+        filename
+    ))
+
+
+def ensure_unpacked(datablock):
+    if datablock.packed_file:
+        logging.info(f"Unpacking {datablock.name}")
+
+        filename = Path(bpy.path.abspath(datablock.filepath)).name
+        datablock.filepath = get_filepath(filename)
+
+        datablock.unpack(method="WRITE_ORIGINAL")
+
+
+class BlFile(ReplicatedDatablock):
+    bl_id = 'file'
+    bl_name = "file"
+    bl_class = Path
+    bl_check_common = False
+    bl_icon = 'FILE'
+    bl_reload_parent = True
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.instance = kwargs.get('instance', None)
+        
+        if self.instance and not self.instance.exists():
+            raise FileNotFoundError(str(self.instance))
+   
+        self.preferences = utils.get_preferences()
+
+    def resolve(self, construct = True):
+        self.instance = Path(get_filepath(self.data['name']))
+        
+        file_exists = self.instance.exists()
+        if not file_exists:
+            logging.debug("File don't exist, loading it.")
+            self._load(self.data, self.instance)
+        
+        return file_exists
+
+
+    def push(self, socket, identity=None, check_data=False):
+        super().push(socket, identity=None, check_data=False)
+        
+        if self.preferences.clear_memory_filecache:
+                del self.data['file']
+
+    def _dump(self, instance=None):
+        """
+        Read the file and return a dict as:
+        {
+            name : filename
+            extension :
+            file: file content
+        }
+        """
+        logging.info(f"Extracting file metadata")
+
+        data = {
+            'name': self.instance.name,
+        }
+
+        logging.info(
+            f"Reading {self.instance.name} content: {self.instance.stat().st_size} bytes")
+
+        try:
+            file = open(self.instance, "rb")
+            data['file'] = file.read()
+
+            file.close()
+        except IOError:
+            logging.warning(f"{self.instance} doesn't exist, skipping")
+        else:
+            file.close()
+
+        return data
+
+    def _load(self, data, target):
+        """
+        Writing the file
+        """
+
+        try:
+            file = open(target, "wb")
+            file.write(data['file'])
+            
+            if self.preferences.clear_memory_filecache:
+                del self.data['file']
+        except IOError:
+            logging.warning(f"{target} doesn't exist, skipping")
+        else:
+            file.close()
+
+    def diff(self):
+        if self.preferences.clear_memory_filecache:
+            return False
+        else:
+            memory_size = sys.getsizeof(self.data['file'])-33
+            disk_size = self.instance.stat().st_size
+            return memory_size != disk_size

multi_user/bl_types/bl_font.py

@@ -0,0 +1,72 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
+import logging
+import os
+from pathlib import Path
+
+import bpy
+
+from .bl_datablock import BlDatablock
+from .bl_file import get_filepath, ensure_unpacked
+from .dump_anything import Dumper, Loader
+
+
+class BlFont(BlDatablock):
+    bl_id = "fonts"
+    bl_class = bpy.types.VectorFont
+    bl_check_common = False
+    bl_icon = 'FILE_FONT'
+    bl_reload_parent = False
+
+    def _construct(self, data):
+        filename = data.get('filename')
+
+        if filename == '<builtin>':
+            return bpy.data.fonts.load(filename)
+        else:
+            return bpy.data.fonts.load(get_filepath(filename))
+
+    def _load(self, data, target):
+        pass
+
+    def _dump(self, instance=None):
+        if instance.filepath  == '<builtin>':
+            filename = '<builtin>'
+        else:
+            filename = Path(instance.filepath).name
+
+        if not filename:
+            raise FileExistsError(instance.filepath)
+
+        return {
+            'filename': filename,
+            'name': instance.name
+        }
+
+    def diff(self):
+        return False
+
+    def _resolve_deps_implementation(self):
+        deps = []
+        if self.instance.filepath and self.instance.filepath != '<builtin>':
+            ensure_unpacked(self.instance)
+
+            deps.append(Path(bpy.path.abspath(self.instance.filepath)))
+
+        return deps

multi_user/bl_types/bl_gpencil.py

@@ -1,83 +1,314 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
 import bpy
 import mathutils
+import numpy as np
 
-from .. import utils
+from .dump_anything import  (Dumper, 
+                                    Loader,
+                                    np_dump_collection,
+                                    np_load_collection)
 from .bl_datablock import BlDatablock
 
+# GPencil data api is structured as it follow: 
+# GP-Object --> GP-Layers --> GP-Frames --> GP-Strokes --> GP-Stroke-Points
 
-def load_gpencil_layer(target=None, data=None, create=False):
+STROKE_POINT = [
+    'co',
+    'pressure',
+    'strength',
+    'uv_factor',
+    'uv_rotation'
 
-    utils.dump_anything.load(target, data)
-    for k,v in target.frames.items():
-        target.frames.remove(v)
-        
-    for frame in data["frames"]:
-        
-        tframe = target.frames.new(data["frames"][frame]['frame_number'])
+]
 
-        # utils.dump_anything.load(tframe, data["frames"][frame])
-        for stroke in data["frames"][frame]["strokes"]:
-            try:
-                tstroke = tframe.strokes[stroke]
-            except:
-                tstroke = tframe.strokes.new()
-            utils.dump_anything.load(
-                tstroke, data["frames"][frame]["strokes"][stroke])
+STROKE = [
+    "aspect",
+    "display_mode",
+    "end_cap_mode",
+    "hardness",
+    "line_width",
+    "material_index",
+    "start_cap_mode",
+    "uv_rotation",
+    "uv_scale",
+    "uv_translation",
+    "vertex_color_fill",
+]
+if bpy.app.version[1] >= 91:
+    STROKE.append('use_cyclic')
+else:
+    STROKE.append('draw_cyclic')
 
-            for point in data["frames"][frame]["strokes"][stroke]["points"]:
-                p = data["frames"][frame]["strokes"][stroke]["points"][point]
+if bpy.app.version[1] >= 83:
+    STROKE_POINT.append('vertex_color')
 
-                tstroke.points.add(1)
-                tpoint = tstroke.points[len(tstroke.points)-1]
+def dump_stroke(stroke):
+    """ Dump a grease pencil stroke to a dict
 
-                utils.dump_anything.load(tpoint, p)
+        :param stroke: target grease pencil stroke
+        :type stroke: bpy.types.GPencilStroke
+        :return: dict
+    """
+
+    assert(stroke)
+
+    dumper = Dumper()
+    dumper.include_filter = [
+        "aspect",
+        "display_mode",
+        "draw_cyclic",
+        "end_cap_mode",
+        "hardeness",
+        "line_width",
+        "material_index",
+        "start_cap_mode",
+        "uv_rotation",
+        "uv_scale",
+        "uv_translation",
+        "vertex_color_fill",
+    ]
+    dumped_stroke = dumper.dump(stroke)
+
+    # Stoke points
+    p_count = len(stroke.points)
+    dumped_stroke['p_count'] = p_count
+    dumped_stroke['points'] = np_dump_collection(stroke.points, STROKE_POINT)
+
+    # TODO: uv_factor, uv_rotation
+
+    return dumped_stroke
+
+
+def load_stroke(stroke_data, stroke):
+    """ Load a grease pencil stroke from a dict
+
+        :param stroke_data: dumped grease pencil stroke 
+        :type stroke_data: dict
+        :param stroke: target grease pencil stroke
+        :type stroke: bpy.types.GPencilStroke
+    """
+    assert(stroke and stroke_data)
+
+    stroke.points.add(stroke_data["p_count"])
+    np_load_collection(stroke_data['points'], stroke.points, STROKE_POINT)
+
+    # HACK: Temporary fix to trigger a BKE_gpencil_stroke_geometry_update to 
+    # fix fill issues
+    stroke.uv_scale = stroke_data["uv_scale"]
+
+def dump_frame(frame):
+    """ Dump a grease pencil frame to a dict
+
+        :param frame: target grease pencil stroke
+        :type frame: bpy.types.GPencilFrame
+        :return: dict
+    """
+
+    assert(frame)
+
+    dumped_frame = dict()
+    dumped_frame['frame_number'] = frame.frame_number
+    dumped_frame['strokes'] = np_dump_collection(frame.strokes, STROKE)
+    dumped_frame['strokes_points'] = []
+
+    for stroke in frame.strokes:
+        dumped_frame['strokes_points'].append(dump_stroke(stroke))
+    
+    return dumped_frame
+
+
+def load_frame(frame_data, frame):
+    """ Load a grease pencil frame from a dict
+
+        :param frame_data: source grease pencil frame
+        :type frame_data: dict
+        :param frame: target grease pencil stroke
+        :type frame: bpy.types.GPencilFrame
+    """
+
+    assert(frame and frame_data)
+
+    for stroke_data in frame_data['strokes_points']:
+        target_stroke = frame.strokes.new()
+        load_stroke(stroke_data, target_stroke)
+
+    np_load_collection(frame_data['strokes'], frame.strokes, STROKE)
+
+def dump_layer(layer):
+    """ Dump a grease pencil layer
+
+        :param layer: target grease pencil stroke
+        :type layer: bpy.types.GPencilFrame
+    """
+
+    assert(layer)
+
+    dumper = Dumper()
+
+    dumper.include_filter = [
+        'info',
+        'opacity',
+        'channel_color',
+        'color',
+        # 'thickness', #TODO: enabling only for annotation
+        'tint_color',
+        'tint_factor',
+        'vertex_paint_opacity',
+        'line_change',
+        'use_onion_skinning',
+        'use_annotation_onion_skinning',
+        'annotation_onion_before_range',
+        'annotation_onion_after_range',
+        'annotation_onion_before_color',
+        'annotation_onion_after_color',
+        'pass_index',
+        # 'viewlayer_render',
+        'blend_mode',
+        'hide',
+        'annotation_hide',
+        'lock',
+        # 'lock_frame',
+        # 'lock_material',
+        # 'use_mask_layer',
+        'use_lights',
+        'use_solo_mode',
+        'select',
+        'show_points',
+        'show_in_front',
+        # 'parent',
+        # 'parent_type',
+        # 'parent_bone',
+        # 'matrix_inverse',
+    ]
+    if layer.id_data.is_annotation:
+        dumper.include_filter.append('thickness')
+
+    dumped_layer = dumper.dump(layer)
+
+    dumped_layer['frames'] = []
+
+    for frame in layer.frames:
+        dumped_layer['frames'].append(dump_frame(frame))
+
+    return dumped_layer
+
+
+def load_layer(layer_data, layer):
+    """ Load a grease pencil layer from a dict
+
+        :param layer_data: source grease pencil layer data
+        :type layer_data: dict
+        :param layer: target grease pencil stroke
+        :type layer: bpy.types.GPencilFrame
+    """
+    # TODO: take existing data in account
+    loader = Loader()
+    loader.load(layer, layer_data)
+
+    for frame_data in layer_data["frames"]:
+        target_frame = layer.frames.new(frame_data['frame_number'])
+
+        load_frame(frame_data, target_frame)
 
 
 class BlGpencil(BlDatablock):
     bl_id = "grease_pencils"
     bl_class = bpy.types.GreasePencil
-    bl_delay_refresh = 5
-    bl_delay_apply = 5
-    bl_automatic_push = True
+    bl_check_common = False
     bl_icon = 'GREASEPENCIL'
+    bl_reload_parent = False
 
-    def construct(self, data):
+    def _construct(self, data):
         return bpy.data.grease_pencils.new(data["name"])
 
-    def load(self, data, target):
-        for layer in target.layers:
-            target.layers.remove(layer)
-
-        if "layers" in data.keys():
-            for layer in data["layers"]:
-                if layer not in target.layers.keys():
-                    gp_layer = target.layers.new(data["layers"][layer]["info"])
-                else:
-                    gp_layer = target.layers[layer]
-                load_gpencil_layer(
-                    target=gp_layer, data=data["layers"][layer], create=True)
-
-        utils.dump_anything.load(target, data)
-
+    def _load_implementation(self, data, target):
         target.materials.clear()
         if "materials" in data.keys():
             for mat in data['materials']:
                 target.materials.append(bpy.data.materials[mat])
 
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
-        data = utils.dump_datablock(pointer, 2)
-        utils.dump_datablock_attibutes(
-            pointer, ['layers'], 9, data)
+        loader = Loader()
+        loader.load(target, data)
+
+        # TODO: reuse existing layer
+        for layer in target.layers:
+            target.layers.remove(layer)
+
+        if "layers" in data.keys():
+            for layer in data["layers"]:
+                layer_data = data["layers"].get(layer)
+
+                # if layer not in target.layers.keys():
+                target_layer = target.layers.new(data["layers"][layer]["info"])
+                # else:
+                #     target_layer = target.layers[layer]
+                #     target_layer.clear()
+
+                load_layer(layer_data, target_layer)
+
+            target.layers.update()
+
+
+
+    def _dump_implementation(self, data, instance=None):
+        assert(instance)
+        dumper = Dumper()
+        dumper.depth = 2
+        dumper.include_filter = [
+            'materials',
+            'name',
+            'zdepth_offset',
+            'stroke_thickness_space',
+            'pixel_factor',
+            'stroke_depth_order'
+        ]
+        data = dumper.dump(instance)
+
+        data['layers'] = {}
+
+        for layer in instance.layers:
+            data['layers'][layer.info] = dump_layer(layer)
+
+        data["active_layers"] = instance.layers.active.info
+        data["eval_frame"] = bpy.context.scene.frame_current
         return data
 
-    def resolve_dependencies(self):
+    def _resolve_deps_implementation(self):
         deps = []
 
-        for material in self.pointer.materials:
+        for material in self.instance.materials:
             deps.append(material)
 
         return deps
 
-    def is_valid(self):
-        return bpy.data.grease_pencils.get(self.data['name'])
+    def layer_changed(self):
+        return self.instance.layers.active.info != self.data["active_layers"]
+
+    def frame_changed(self):
+        return  bpy.context.scene.frame_current != self.data["eval_frame"]
+
+    def diff(self):
+        if self.layer_changed() \
+                or self.frame_changed() \
+                or bpy.context.mode == 'OBJECT' \
+                or self.preferences.sync_flags.sync_during_editmode:
+            return super().diff()
+        else:
+            return False

multi_user/bl_types/bl_image.py

@@ -1,83 +1,123 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+
+import logging
+import os
+from pathlib import Path
+
 import bpy
 import mathutils
-import os
 
-from .. import utils, environment
+from .. import utils
 from .bl_datablock import BlDatablock
+from .dump_anything import Dumper, Loader
+from .bl_file import get_filepath, ensure_unpacked
 
-def dump_image(image):
-    pixels = None
-    if image.source == "GENERATED":
-        img_name = "{}.png".format(image.name)
+format_to_ext = {
+    'BMP': 'bmp',
+    'IRIS': 'sgi',
+    'PNG': 'png',
+    'JPEG': 'jpg',
+    'JPEG2000': 'jp2',
+    'TARGA': 'tga',
+    'TARGA_RAW': 'tga',
+    'CINEON': 'cin',
+    'DPX': 'dpx',
+    'OPEN_EXR_MULTILAYER': 'exr',
+    'OPEN_EXR': 'exr',
+    'HDR': 'hdr',
+    'TIFF': 'tiff',
+    'AVI_JPEG': 'avi',
+    'AVI_RAW': 'avi',
+    'FFMPEG': 'mpeg',
+}
 
-        image.filepath_raw = os.path.join(environment.CACHE_DIR, img_name)
-        image.file_format = "PNG"
-        image.save()
-
-    if image.source == "FILE":
-        image_path = bpy.path.abspath(image.filepath_raw)
-        image_directory = os.path.dirname(image_path)
-        os.makedirs(image_directory, exist_ok=True)
-        image.save()
-        file = open(image_path, "rb")
-        pixels = file.read()
-        file.close()
-    else:
-        raise ValueError()
-    return pixels
 
 class BlImage(BlDatablock):
     bl_id = "images"
     bl_class = bpy.types.Image
-    bl_delay_refresh = 0
-    bl_delay_apply = 1
-    bl_automatic_push = False
+    bl_check_common = False
     bl_icon = 'IMAGE_DATA'
+    bl_reload_parent = False
 
-    def construct(self, data):
+    def _construct(self, data):
         return bpy.data.images.new(
-                name=data['name'],
-                width=data['size'][0],
-                height=data['size'][1]
-            )
+            name=data['name'],
+            width=data['size'][0],
+            height=data['size'][1]
+        )
 
-    def load(self, data, target):
-        image = target
+    def _load(self, data, target):
+        loader = Loader()
+        loader.load(data, target)
 
-        img_name = "{}.png".format(image.name)
+        target.source = 'FILE'
+        target.filepath_raw = get_filepath(data['filename'])
+        target.colorspace_settings.name = data["colorspace_settings"]["name"]
 
-        img_path = os.path.join(environment.CACHE_DIR, img_name)
+    def _dump(self, instance=None):
+        assert(instance)
 
-        file = open(img_path, 'wb')
-        file.write(data["pixels"])
-        file.close()
+        filename = Path(instance.filepath).name
 
-        image.source = 'FILE'
-        image.filepath = img_path
-        image.colorspace_settings.name = data["colorspace_settings"]["name"]
+        data = {
+            "filename": filename
+        }
 
-
-    def dump_implementation(self, data, pointer=None):
-        assert(pointer)
-        data = {}
-        data['pixels'] = dump_image(pointer)
-        dumper = utils.dump_anything.Dumper()
+        dumper = Dumper()
         dumper.depth = 2
-        dumper.include_filter = [   
-                "name",
-                'size',
-                'height',
-                'alpha',
-                'float_buffer',
-                'filepath',
-                'source',
-                'colorspace_settings']
-        data.update(dumper.dump(pointer))
-
+        dumper.include_filter = [
+            "name",
+            'size',
+            'height',
+            'alpha',
+            'float_buffer',
+            'alpha_mode',
+            'colorspace_settings']
+        data.update(dumper.dump(instance))
         return data
 
     def diff(self):
-        return False
-    
-    def is_valid(self):
-        return bpy.data.images.get(self.data['name'])
+        if self.instance.is_dirty:
+            self.instance.save()
+
+        if self.instance and (self.instance.name != self.data['name']):
+            return True
+        else:
+            return False
+
+    def _resolve_deps_implementation(self):
+        deps = []
+
+        if self.instance.packed_file:
+            filename = Path(bpy.path.abspath(self.instance.filepath)).name
+            self.instance.filepath_raw = get_filepath(filename)
+            self.instance.save()
+            # An image can't be unpacked to the modified path
+            # TODO: make a bug report
+            self.instance.unpack(method="REMOVE")
+
+        elif self.instance.source == "GENERATED":
+            filename = f"{self.instance.name}.png"
+            self.instance.filepath = get_filepath(filename)
+            self.instance.save()
+
+        if self.instance.filepath:
+            deps.append(Path(bpy.path.abspath(self.instance.filepath)))
+
+        return deps