Basic concepts

Overview

Unity Cloud Collaboration provides a comprehensive framework for implementing real-time collaboration features in your Unity projects. To effectively use the Collaboration SDK, it's important to understand the core concepts that form the foundation of the system. This document explains these fundamental building blocks and how they work together.

Key concepts

Annotations

Annotations are the primary communication elements in the Collaboration system. They represent comments, feedback, or notes that can be attached to specific targets within your Unity project.

Key characteristics of annotations:

  • Content: Annotations contain text content that expresses ideas, feedback, or questions, but also attachments and metadata.
  • Target: Each annotation is attached to a specific target. A target defines the connection between an annotation and the annotated object
  • Mentions: Allow users to notify each other directly.
  • State: Annotations can have different states, such as "active" or "draft," indicating their current status.
  • Creator: Every annotation has an associated creator who authored it.
  • Timestamp: Annotations record when they were created and last modified.

Threads

Threads organize annotations into conversations, enabling structured discussions and feedback exchanges.

Key characteristics of threads:

  • Root Annotation: Each thread begins with a root annotation that establishes the topic.
  • Replies: Threads can contain multiple reply annotations, creating a hierarchical conversation structure.
  • Participants: Users who contribute to a thread are considered participants.
  • Subscription: Users can subscribe to threads to receive notifications about updates.
  • Notifications: Threads can trigger notifications that notify subscribed users of activities on a thread.
  • Structure: Threads are structured with a single level of nesting.

Targets

The Target field defines the connection between an annotation and the annotated object. It is represented by a / delimited path. For example, in Asset Manager, the Target format for an Asset is:

assets/projects/{projectId}/assets/{assetId}

Subscriptions

Subscriptions control notification delivery and help users stay informed about relevant discussions.

Key aspects of subscriptions:

  • User-Thread Connection: Subscriptions link users to specific threads they want to monitor.
  • Notification Triggering: When events occur on a subscribed thread, notifications are generated for subscribed users.
  • Automatic Subscription: Users are typically auto-subscribed to threads they create or reply to.
  • Manual Management: Users can manually subscribe to or unsubscribe from threads based on their interests.

Attachments

Attachments enhance annotations by adding additional content beyond texts. Attachments can either be file attachments or simply metadata attachments. The purpose of these attachments is to enrich the annotation with extra information, whether that is screenshots, location information about the asset’s file, or sketches to place over the asset’s file. While files and other types of attachments are different in how they are stored, there is a significant overlap in how they are presented. Attachments are also managed completely separately from annotations, as this simplifies the interactions significantly on the API. However, for ease of use, attachments can be created as part of the annotation creation process, and attachments are returned as part of the annotation information.

Types of attachments:

  • File Attachments: External files such as documents, images, or audio clips.
  • Spatial 3D Attachments: Data that represents point in 3D space in scene with additional camera settings.

Reactions

Reactions provide a lightweight way for users to respond to annotations without creating full replies. Users can react to an annotation by adding an emoji in a similar way to how other applications or platforms work. The Collaboration Service provides endpoints for creating and removing reactions, supporting single character UTF-16 encoded emojis and surrogate pairs.

Characteristics of reactions:

  • Emoji/Symbol Based: Reactions are typically represented by emojis or symbols.
  • User Association: Each reaction is associated with the user who created it.
  • Counts: Multiple users can apply the same reaction, which are then counted and displayed together.
  • Quick Feedback: Reactions enable quick sentiment sharing without thread clutter.

Annotation hierarchy

The thread structure only allows one level of replies.

Thread
└── Root Annotation (Annotation1)
       ├── Annotation2 (Reply to Annotation1)
       ├── Annotation3 (Reply to Annotation1)
       └── Annotation4 (Reply to Annotation1)
  • A thread starts with a root annotation.
  • Replies can be added (only) to the root, creating a hierarchical structure.
  • Replies to replies are not allowed.
  • This hierarchy enables organized conversations with a clear context.

Subscription flow

User ──(subscribes to)──> Thread
  │
  └──(receives)──> Notifications <──(generated by)─── Thread Events
  • Users subscribe to threads of interest
  • Thread events (new replies, status changes) generate notifications
  • Subscribed users receive these notifications to stay informed

Best practices

When working with the Collaboration SDK, consider these best practices:

  1. Targeted Annotations: Encourage users to create annotations with specific, clear targets to provide proper context.
  2. Thread Organization: Maintain a clean thread structure by creating new root annotations for distinct topics rather than extending discussions in unrelated threads.
  3. Judicious Subscriptions: Subscribe only to relevant threads to avoid notification overload while staying informed about important discussions.
  4. Rich Context: Use attachments when the text alone is insufficient to convey ideas or feedback.
  5. Status Management: Regularly update annotation statuses to reflect their current state (e.g., marking resolved issues as "resolved").
  6. Reaction Etiquette: Use reactions for quick acknowledgments and sentiments, reserving replies for substantial responses.

For detailed information on implementing specific features, see the use cases section in the documentation.

Note

These concepts provide the foundation for building a collaborative environment in your Unity projects. Understanding how they interrelate will help you design effective collaboration workflows tailored to your team's needs.

Warning

This product allows you to input developer defined data (such as custom fields, metadata, and assets). You must not use the product to input or collect personal data, unless such information is specifically required or requested by the product.