@needle-tools/engine/lib/engine-components/SyncedTransform.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { Behaviour } from "./Component.js";
export declare const SyncedTransformIdentifier = "STRS";
/**
 * Creates a flatbuffer model containing the transform data of a game object. Used by {@link SyncedTransform}
 * @param guid The unique identifier of the object to sync
 * @param b The behavior component containing transform data
 * @param fast Whether to use fast mode synchronization (syncs more frequently)
 * @returns A Uint8Array containing the serialized transform data
 */
export declare function createTransformModel(guid: string, b: Behaviour, fast?: boolean): Uint8Array;
/**
 * SyncedTransform synchronizes position and rotation of a GameObject across the network.
 * When users interact with an object (e.g., via {@link DragControls}), they automatically
 * take ownership and their changes are broadcast to other users.
 *
 * **Features:**
 * - Automatic ownership transfer when interacting
 * - Smooth interpolation of remote updates
 * - Physics integration (can override kinematic state)
 * - Fast mode for rapidly moving objects
 *
 * **Requirements:**
 * - Active network connection via {@link SyncedRoom}
 * - Objects must have unique GUIDs (set automatically in Unity/Blender export)
 *
 * **Ownership:**
 * This component uses {@link OwnershipModel} internally to manage object ownership.
 * Only the client that owns an object can send transform updates. Use `requestOwnership()`
 * before modifying the transform, or check `hasOwnership()` to see if you can modify it.
 *
 * **Debug:** Use `?debugsync` URL parameter for logging.
 *
 * @example Basic networked object
 * ```ts
 * // Add to any object you want synced
 * const sync = myObject.addComponent(SyncedTransform);
 * sync.fastMode = true; // For fast-moving objects
 *
 * // Request ownership before modifying
 * sync.requestOwnership();
 * myObject.position.x += 1;
 * ```
 *
 * - Example: https://engine.needle.tools/samples/collaborative-sandbox
 *
 * @summary Synchronizes object transform over the network with ownership management
 * @category Networking
 * @group Components
 * @see {@link SyncedRoom} for room/session management
 * @see {@link OwnershipModel} for ownership management details
 * @see {@link DragControls} for interactive dragging with sync
 * @see {@link Duplicatable} for networked object spawning
 * @link https://engine.needle.tools/docs/networking.html
 */
export declare class SyncedTransform extends Behaviour {
    /** When true, overrides physics behavior when this object is owned by the local user */
    overridePhysics: boolean;
    /** Whether to smoothly interpolate position changes when receiving updates */
    interpolatePosition: boolean;
    /** Whether to smoothly interpolate rotation changes when receiving updates */
    interpolateRotation: boolean;
    /** When true, sends updates at a higher frequency, useful for fast-moving objects */
    fastMode: boolean;
    /** When true, notifies other clients when this object is destroyed */
    syncDestroy: boolean;
    private _model;
    private _needsUpdate;
    private rb;
    private _wasKinematic;
    private _receivedDataBefore;
    private _targetPosition;
    private _targetRotation;
    private _receivedFastUpdate;
    private _shouldRequestOwnership;
    /**
     * Requests ownership of this object on the network.
     * You need to be connected to a room for this to work.
     * Call this before modifying the object's transform to ensure your changes are synchronized.
     *
     * @example
     * ```ts
     * // Request ownership before modifying
     * syncedTransform.requestOwnership();
     * this.gameObject.position.y += 1;
     * ```
     * @see {@link OwnershipModel.requestOwnership} for more details
     */
    requestOwnership(): void;
    /**
     * Free ownership of this object on the network.
     * You need to be connected to a room for this to work.
     * This will also be called automatically when the component is disabled.
     * Call this when you're done modifying an object to allow other users to interact with it.
     * @see {@link OwnershipModel.freeOwnership} for more details
     */
    freeOwnership(): void;
    /**
     * Checks if this client has ownership of the object.
     * @returns `true` if this client has ownership, `false` if not, `undefined` if ownership state is unknown
     * @see {@link OwnershipModel.hasOwnership} for more details
     */
    hasOwnership(): boolean | undefined;
    /**
     * Checks if the object is owned by any client (local or remote).
     * @returns `true` if the object is owned, `false` if not, `undefined` if ownership state is unknown
     * @see {@link OwnershipModel.isOwned} for more details
     */
    isOwned(): boolean | undefined;
    private joinedRoomCallback;
    private receivedDataCallback;
    /** @internal */
    awake(): void;
    /** @internal */
    onDestroy(): void;
    /**
     * Attempts to retrieve and apply the last known network state for this transform
     */
    private tryGetLastState;
    private tempEuler;
    /**
     * Handles incoming network data for this transform
     * @param data The model containing transform information
     */
    private onReceivedData;
    /**
     * @internal
     * Initializes tracking of position and rotation when component is enabled
     */
    onEnable(): void;
    /**
     * @internal
     * Releases ownership when component is disabled
     */
    onDisable(): void;
    private receivedUpdate;
    private lastPosition;
    private lastRotation;
    private lastScale;
    /**
     * @internal
     * Handles transform synchronization before each render frame
     * Sends updates when owner, receives and applies updates when not owner
     */
    onBeforeRender(): void;
}