**Language / Langue :** [[fr:editeur:collaboration|FR]] | **EN**

====== Collaborative editing ======

Since version 4.12, the graphical editor lets you write a scenario **together, in real time**. A collaborative session is a temporary shared ''.jdrproj'' document with a private link: every author works in their usual editor (web or desktop) and sees the others' changes appear live.

<WRAP center round important 80%>
The session **saves nothing**: the shared document lives in the server's memory for the duration of the session. **Export or save** regularly from your editor — and always before leaving.
</WRAP>

===== Overview =====

  * A session = a shared document + a **private token** (inside the link). Anyone with the link can join.
  * Up to **10 simultaneous authors**, web and desktop clients freely mixed.
  * Two ways to host:
    * on the **JDR-Bot web server** (simplest);
    * on **your own PC** through the desktop version (TCP port ''41212''), without relying on the public server.

===== Create and join (web) =====

  - Open your scenario in the web editor.
  - **Tools → Create collaborative session**: name the session; the share link is copied automatically.
  - Send the link to your co-authors. The ''Collab'' status (bottom bar) shows connected participants, each with their own colour.

To join:

  * simply open the **received link** (''.../editor?collab=...'') — the editor joins the session on load;
  * or **Tools → Join collaborative session** and paste the link (or the bare token).

The session document **replaces** whatever was open in your editor — save your current work before joining.

===== From the desktop =====

==== Joining a web session ====

**Tools → Join collaborative session**, paste the link. The desktop version asks for (and remembers) the JDR-Bot web **server URL** if it cannot be deduced from the link.

==== Hosting locally ====

The desktop version can host the session itself, without any public server:

  - **Tools → Host local session**: a collaborative server starts on your PC (TCP port ''41212'') and the **LAN link** is copied.
  - On the **same local network** (home, club...), co-authors open that link in their browser or desktop app: it just works.
  - **Over the Internet**, you must open/forward port ''41212'' on your router to your PC (same as hosting a game), then share the link with your public IP.

The desktop host and the guests (web or desktop) work in the same session with the same features. The session stops when the host closes the application.

===== During the session =====

  * **Presence**: the participant list (name + colour) is visible in the ''Collab'' status and updated in real time.
  * **Propagation**: every change (text, variable, room added/removed, rename...) shows up for the others within ~1 second, without reloading.
  * **Soft lock**: while an author edits a field, the others see an indicator with their name and colour. The lock is **advisory** — it warns, but never prevents typing in the same place. It stays active while the field keeps focus and disappears when the author leaves it (or disconnects).
  * **Copy session link** (Tools menu or ''Collab'' status): at any time, to invite someone mid-session.

===== Conflicts and synchronization =====

The session works with **versions**: every change is sent as a small patch based on the current document version.

  * **Different fields**: two authors editing different things at the same time (two rooms, a room and a variable...) are **merged automatically** — no friction, no message.
  * **Same field**: the **last writer wins**. The other author is resynchronized onto the winning value, with an explicit message. No mangled text, no half-merge.
  * **Concurrent deletions**: deleting a room while someone else edits the room list also triggers a resynchronization (so nobody ever edits the wrong room).

==== The local draft ====

When a resynchronization discards your unsent changes, they are **not lost**: a "Collaborative resynchronization" window offers to **copy** or **export the local copy** (''.jdrproj''). The editor stays marked as "modified" until that draft is dealt with — closing or leaving the session will ask for confirmation.

===== Undo / Redo (Ctrl+Z / Ctrl+Y) =====

The undo history is **local to each author**: it stores full snapshots of //your// document, not the other authors' changes.

  * **Joining a session or being resynchronized clears the history.** By design: those steps described a document that is no longer the session's.
  * **Ctrl+Z restores your snapshot, including over changes received in the meantime.** If a co-author edited room 3 after your last action and you undo, their change is reverted for everyone — cleanly, as if you had edited it yourself.
  * **Last writer wins** — the same rule as two simultaneous edits of the same field.

<WRAP center round tip 80%>
In a collaborative session, prefer immediate undos (right after your own action) — they only touch your own changes. Warn your co-authors before a deep undo.
</WRAP>

===== Saving and exporting =====

  * The server **never saves** the scenario: it only synchronizes the authors.
  * Every participant can use **Export YAML** / **Save** at any time from their own editor — everyone works on the same current document, so the exports are identical.
  * Team tip: appoint a "keeper" who exports regularly, especially before breaks.

===== End of session =====

  * **Tools → Leave collaboration**: clean disconnect (confirmation asked if unsaved changes remain).
  * **Empty session**: once everyone has left, the session stays joinable for ~2 minutes (reconnection grace), then it is deleted. The old link stops working.
  * **Idle session**: if nobody touches anything (tabs closed or hidden) for 30 minutes, the session expires. An open and **visible** tab counts as present — no expiration while the team is around, even without editing.
  * **Server restart**: sessions live in memory — they are lost. Create a new session and share the link again (your local documents and exports are unaffected).

===== Limits and safeguards =====

^ Limit ^ Value ^
| Participants per session | 10 |
| Shared project size | 8 MB |
| Single change size | 256 KB (a huge paste is refused cleanly) |
| Change rate | ~120 messages/min per author |
| Automatic reconnection | ~20 attempts (~4 min), then stops with a message — the local document is kept |

After a network drop, the editor reconnects by itself and resynchronizes. If the session expired in the meantime, a clear message says so.

===== Common messages =====

^ Message ^ Meaning ^
| //Collaborative session not found or expired// | The token no longer matches a session (expired, server restarted, wrong link). Create/request a new link. |
| //Collaborative session full// | 10 participants already connected. |
| //Too many messages// | Change rate too high — wait a few seconds, everything resumes. |
| //Document resynchronized with the session// | A conflict was resolved in favour of another author; your discarded changes are in the local draft. |
| //Collaborative reconnection stopped// | Server unreachable after several attempts. Your local document is intact; rejoin via the link once the server responds. |

See also: [[en:editeur:presentation|Editor overview]] · [[en:editeur:linter-export|Linter and export]]