Class OwnershipModel

Manages ownership of networked objects or components.

In multiplayer scenarios, ownership determines which client has authority to modify an object. The networking server rejects changes from clients that don't own an object. This prevents conflicts when multiple users try to manipulate the same object simultaneously.

Ownership states:

  • hasOwnership: This client owns the object and can modify it
  • isOwned: Some client (could be local or remote) owns the object
  • undefined: Ownership state is unknown (not yet queried)

Typical workflow:

  1. Request ownership before modifying an object
  2. Make your changes while you have ownership
  3. Free ownership when done (or keep it if still interacting)

Example: Basic usage

export class MyComponent extends Behaviour {
  private ownership?: OwnershipModel;

  awake() {
    this.ownership = new OwnershipModel(this.context.connection, this.guid);
  }

  onClick() {
    // Request ownership before modifying the object
    this.ownership.requestOwnership();
  }

  update() {
    if (this.ownership.hasOwnership) {
      // Safe to modify and sync the object
      this.gameObject.position.y += 0.01;
    }
  }

  onDisable() {
    // Release ownership when done
    this.ownership.freeOwnership();
    this.ownership.destroy();
  }
}

Example: Async ownership

async modifyObject() {
  try {
    await this.ownership.requestOwnershipAsync();
    // Now guaranteed to have ownership
    this.transform.position.x = 5;
  } catch(e) {
    console.log("Failed to gain ownership");
  }
}

See

SyncedTransform for a complete example of ownership in action

Link

https://engine.needle.tools/docs/networking.html

Constructors

constructor

Properties

guid

Accessors

hasOwnership isConnected isOwned

Methods

destroy freeOwnership requestOwnership requestOwnershipAsync requestOwnershipIfNotOwned updateIsOwned

Constructors

constructor

Properties

guid

guid: string

The unique identifier (GUID) of the object this ownership model manages

Accessors

hasOwnership

  • get hasOwnership(): boolean

    Checks if the local client has ownership of this object.

    Returns boolean

    true if this client owns the object and can modify it, false otherwise

isConnected

  • get isConnected(): boolean

    Checks if Needle Engine networking is connected to a websocket. Note that this is not equal to being connected to a room. If you want to check if Needle Engine is connected to a networking room use the isInRoom property.

    Returns boolean

    true if connected to the websocket.

isOwned

  • get isOwned(): undefined | boolean

    Checks if anyone (local or remote client) has ownership of this object.

    Returns undefined | boolean

    true if someone owns the object, false if no one owns it, undefined if unknown

Methods

destroy

  • destroy(): void

    Cleans up event listeners and resources. Call this when the OwnershipModel is no longer needed (e.g., in onDestroy()).

    Returns void

freeOwnership

  • freeOwnership(): OwnershipModel

    Releases ownership of this object, allowing others to take control. Call this when you're done modifying an object to allow other users to interact with it.

    Returns OwnershipModel

    this OwnershipModel instance for method chaining

requestOwnership

  • requestOwnership(): OwnershipModel

    Requests ownership of this object from the networking server. Ownership may not be granted immediately - check hasOwnership property or use requestOwnershipAsync().

    Returns OwnershipModel

    this OwnershipModel instance for method chaining

requestOwnershipAsync

  • requestOwnershipAsync(): Promise<OwnershipModel>

    Requests ownership and waits asynchronously until ownership is granted or timeout occurs.

    Returns Promise<OwnershipModel>

    Promise that resolves with this OwnershipModel when ownership is gained

    Throws

    Rejects with "Timeout" if ownership is not gained within ~1 second

    Example

    try {
      await ownership.requestOwnershipAsync();
      // Ownership granted, safe to modify object
    } catch(e) {
      console.warn("Could not gain ownership:", e);
    }

requestOwnershipIfNotOwned

  • requestOwnershipIfNotOwned(): OwnershipModel

    Requests ownership only if the object is not currently owned by anyone. Internally checks ownership state first, then requests ownership if free.

    Returns OwnershipModel

    this OwnershipModel instance for method chaining

updateIsOwned

  • updateIsOwned(): void

    Queries the server to update the isOwned state. Call this to check if anyone currently has ownership.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods