@needle-tools/engine 4.13.0 → 4.13.1

package/src/engine/engine_networking.ts

@@ -4,6 +4,8 @@ let networkingServerUrl: string | undefined = "wss://networking.needle.tools/soc
 import * as flatbuffers from 'flatbuffers';
 import { type Websocket } from 'websocket-ts';
 
+import type { Networking } from "../engine-components/Networking.js";
+import type { SyncedRoom } from "../engine-components/SyncedRoom.js";
 import * as schemes from "../engine-schemes/schemes.js";
 import { isDevEnvironment } from './debug/index.js';
 import { Telemetry } from './engine_license.js';
@@ -116,27 +118,95 @@ declare type OwnershipResponse = {
 
 declare type WebsocketSendType = IModel | object | boolean | null | string | number;
 
-/** Class for abstracting the concept of ownership regarding a networked object or component.   
- * A component that is owned by another user can not be modified through networking (the server will reject changes) */
+/**
+ * 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
+ * ```ts
+ * 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
+ * ```ts
+ * 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 {@link SyncedTransform} for a complete example of ownership in action
+ * @link https://engine.needle.tools/docs/networking.html
+ */
 export class OwnershipModel {
 
+    /** The unique identifier (GUID) of the object this ownership model manages */
     public guid: string;
     private connection: NetworkConnection;
 
+    /**
+     * Checks if the local client has ownership of this object.
+     * @returns `true` if this client owns the object and can modify it, `false` otherwise
+     */
     public get hasOwnership(): boolean {
         return this._hasOwnership;
     }
 
     // TODO: server should just send id to everyone
 
-    /** @returns true of anyone has ownership */
+    /**
+     * Checks if anyone (local or remote client) has ownership of this object.
+     * @returns `true` if someone owns the object, `false` if no one owns it, `undefined` if unknown
+     */
     public get isOwned(): boolean | undefined {
         return this._isOwned;
     }
 
-    /** 
+    /**
      * 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 true if connected to the websocket. 
+     * @returns true if connected to the websocket.
      */
     public get isConnected(): boolean {
         return this.connection.isConnected;
@@ -162,6 +232,10 @@ export class OwnershipModel {
 
     private _isWaitingForOwnershipResponseCallback: Function | null = null;
 
+    /**
+     * Queries the server to update the `isOwned` state.
+     * Call this to check if anyone currently has ownership.
+     */
     public updateIsOwned() {
         this.connection.send(OwnershipEvent.RequestHasOwner, { guid: this.guid });
     }
@@ -172,6 +246,11 @@ export class OwnershipModel {
         }
     }
 
+    /**
+     * Requests ownership only if the object is not currently owned by anyone.
+     * Internally checks ownership state first, then requests ownership if free.
+     * @returns this OwnershipModel instance for method chaining
+     */
     public requestOwnershipIfNotOwned(): OwnershipModel {
         if (this._isWaitingForOwnershipResponseCallback !== null) return this;
         this._isWaitingForOwnershipResponseCallback = this.waitForHasOwnershipRequestResponse.bind(this);
@@ -197,6 +276,20 @@ export class OwnershipModel {
     }
 
 
+    /**
+     * Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
+     * @returns Promise that resolves with this OwnershipModel when ownership is gained
+     * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
+     * @example
+     * ```ts
+     * try {
+     *   await ownership.requestOwnershipAsync();
+     *   // Ownership granted, safe to modify object
+     * } catch(e) {
+     *   console.warn("Could not gain ownership:", e);
+     * }
+     * ```
+     */
     public requestOwnershipAsync(): Promise<OwnershipModel> {
         return new Promise((resolve, reject) => {
             this.requestOwnership();
@@ -212,12 +305,22 @@ export class OwnershipModel {
         });
     }
 
+    /**
+     * Requests ownership of this object from the networking server.
+     * Ownership may not be granted immediately - check `hasOwnership` property or use `requestOwnershipAsync()`.
+     * @returns this OwnershipModel instance for method chaining
+     */
     public requestOwnership(): OwnershipModel {
         if (debugOwner) console.log("Request ownership", this.guid);
         this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
         return this;
     }
 
+    /**
+     * 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 this OwnershipModel instance for method chaining
+     */
     public freeOwnership(): OwnershipModel {
         // TODO: abort "requestOwnershipIfNotOwned"
         this.connection.send(OwnershipEvent.RemoveOwnership, { guid: this.guid });
@@ -228,6 +331,10 @@ export class OwnershipModel {
         return this;
     }
 
+    /**
+     * Cleans up event listeners and resources.
+     * Call this when the OwnershipModel is no longer needed (e.g., in `onDestroy()`).
+     */
     public destroy() {
         this.connection.stopListen(OwnershipEvent.GainedOwnership, this._gainSubscription);
         this.connection.stopListen(OwnershipEvent.LostOwnership, this._lostSubscription);
@@ -265,10 +372,46 @@ export declare type BinaryCallback = {
     (data: any | flatbuffers.ByteBuffer): void;
 }
 
-/** Main class to communicate with the networking backend 
- * @link https://engine.needle.tools/docs/networking.html
- * 
-*/
+/**
+ * Main class for multiuser networking. Access via `this.context.connection` from any component.
+ *
+ * **About GUIDs:**
+ * In Needle Engine networking, GUIDs (Globally Unique Identifiers) are used to identify objects and components across the network.  
+ * Every GameObject and Component has a unique `guid` property that remains consistent across all clients.  
+ * GUIDs are automatically assigned (e.g. during export from Unity/Blender) and are essential for:  
+ * - Object ownership management (see {@link OwnershipModel})
+ * - State synchronization (storing and retrieving object state)
+ * - Identifying which object received a network message
+ *
+ * When working with networking, you'll typically use `this.guid` to identify your component or `this.gameObject.guid` for the GameObject.
+ *
+ * @example Joining a room
+ * ```ts
+ * this.context.connection.connect();
+ * this.context.connection.joinRoom("my-room");
+ * ```
+ * @example Listening to events
+ * ```ts
+ * this.context.connection.beginListen("my-event", (data) => {
+ *   console.log("Received:", data);
+ * });
+ * ```
+ * @example Sending data
+ * ```ts
+ * this.context.connection.send("my-event", { message: "Hello" });
+ * ```
+ * @example Using GUIDs for object identification
+ * ```ts
+ * // Get state for a specific object by its GUID
+ * const state = this.context.connection.tryGetState(this.guid);
+ *
+ * // Delete remote state for an object
+ * this.context.connection.sendDeleteRemoteState(this.guid);
+ * ```
+ * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link OwnershipModel} for object ownership
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
+ */
 export class NetworkConnection implements INetworkConnection {
 
     private context: Context;
@@ -287,7 +430,18 @@ export class NetworkConnection implements INetworkConnection {
     }
 
     /**
-     * Returns the state of a given guid.
+     * Returns the cached network state for a given GUID.  
+     * The state is stored locally whenever network updates are received for that object.  
+     * @param guid The unique identifier of the object whose state you want to retrieve
+     * @returns The cached state object, or `null` if no state exists for this GUID
+     * @example
+     * ```ts
+     * // Get the last known state for this component
+     * const myState = this.context.connection.tryGetState(this.guid);
+     * if (myState) {
+     *   console.log("Found cached state:", myState);
+     * }
+     * ```
      */
     public tryGetState(guid: string): IModel | null {
         if (guid === "invalid") return null;
@@ -307,7 +461,7 @@ export class NetworkConnection implements INetworkConnection {
     }
 
     /** 
-     * 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.
+     * 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 `{@link isInRoom}` property.
      * @returns true if connected to the websocket. 
      */
     public get isConnected(): boolean {
@@ -372,7 +526,7 @@ export class NetworkConnection implements INetworkConnection {
         return target;
     }
 
-    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `SyncedRoom` component as well */
+    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `{@link SyncedRoom}` component as well */
     public joinRoom(room: string, viewOnly: boolean = false): boolean {
         if (!room) {
             console.error("Missing room name, can not join: \"" + room + "\"");
@@ -426,7 +580,18 @@ export class NetworkConnection implements INetworkConnection {
         return this.sendWithWebsocket(key, data, queue);
     }
 
-    /** Use to delete state for a given guid on the server */
+    /**
+     * Deletes the network state for a specific object on the server.  
+     * This removes the object's state from the room, preventing it from being sent to newly joining users.  
+     * @param guid The unique identifier of the object whose state should be deleted
+     * @example
+     * ```ts
+     * // When destroying a networked object, clean up its server state
+     * onDestroy() {
+     *   this.context.connection.sendDeleteRemoteState(this.guid);
+     * }
+     * ```
+     */
     public sendDeleteRemoteState(guid: string) {
         this.send("delete-state", { guid: guid, dontSave: true });
         delete this._state[guid];
@@ -469,7 +634,7 @@ export class NetworkConnection implements INetworkConnection {
     }
 
     /** Use to start listening to networking events.   
-     * To unsubscribe from events use the `stopListen` method.   
+     * To unsubscribe from events use the `{@link stopListen}` method.   
      * See the example below for typical usage:
      * 
      * ### Component Example
@@ -501,7 +666,7 @@ export class NetworkConnection implements INetworkConnection {
     public stopListening(key: (string & {}) | OwnershipEvent | OwnershipEventNamesIncoming | RoomEventsIncoming | RoomEvents, callback: Function | null) { return this.stopListen(key, callback); }
 
     /** Use to stop listening to networking events  
-     * To subscribe to events use the `beginListen` method.   
+     * To subscribe to events use the `{@link beginListen}` method.   
      * See the example below for typical usage:
      * 
      * ### Component Example
@@ -548,12 +713,16 @@ export class NetworkConnection implements INetworkConnection {
 
     private netWebSocketUrlProvider?: INetworkingWebsocketUrlProvider;
 
-    /** Use to override the networking server backend url. This is what the `Networking` component uses to modify the backend url */
+    /** Use to override the networking server backend url.   
+     * This is what the `{@link Networking}` component uses to modify the backend url.
+     **/
     public registerProvider(prov: INetworkingWebsocketUrlProvider) {
         this.netWebSocketUrlProvider = prov;
     }
 
-    /** Used to connect to the networking server */
+    /** Used to connect to the networking server
+     * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
+    */
     public async connect(url?: string) {
         if (this.connected && url && url !== networkingServerUrl) {
             return Promise.reject("Can not connect to different server url. Please disconnect first.");

package/src/engine/engine_networking_auto.ts

@@ -176,15 +176,42 @@ export declare type SyncFieldOptions = {
 export declare type FieldChangedCallbackFn = (newValue: any, previousValue: any) => void | boolean | any;
 
 /**
- * **Decorate a field to be automatically networked synced**  
- * *Primitive* values are all automatically synced (like string, boolean, number).   
- * For *arrays or objects* make sure to re-assign them (e.g. `this.mySyncField = this.mySyncField`) to trigger an update
- * 
- * @param onFieldChanged name of a callback function that will be called when the field is changed.
- * You can also pass in a function like so: syncField(myClass.prototype.myFunctionToBeCalled)  
- * Note: if you return `false` from this function you'll prevent the field from being synced with other clients
- * (for example a networked color is sent as a number and may be converted to a color in the receiver again)
- * Parameters: (newValue, previousValue)
+ * Marks a field for automatic network synchronization across connected clients.  
+ * When a synced field changes, the new value is automatically broadcast to all users in the room.  
+ *
+ * Primitives (string, number, boolean) sync automatically.  
+ * For arrays/objects, reassign to trigger sync: `this.myArray = this.myArray`  
+ *
+ * @param onFieldChanged Optional callback when the field changes (locally or from network).  
+ * Return `false` to prevent syncing this change to others.
+ *
+ * @example Basic sync
+ * ```ts
+ * class MyComponent extends Behaviour {
+ *   @syncField() playerScore: number = 0;
+ * }
+ * ```
+ * @example With change callback
+ * ```ts
+ * class MyComponent extends Behaviour {
+ *   @syncField("onHealthChanged") health: number = 100;
+ *
+ *   onHealthChanged(newValue: number, oldValue: number) {
+ *     console.log(`Health: ${oldValue} → ${newValue}`);
+ *   }
+ * }
+ * ```
+ * @example Preventing sync (one-way)
+ * ```ts
+ * class MyComponent extends Behaviour {
+ *   @syncField(function(newVal, oldVal) {
+ *     // Process incoming value but don't sync our changes
+ *     return false;
+ *   }) serverControlled: string = "";
+ * }
+ * ```
+ * @see {@link serializable} for editor serialization
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
  */
 export const syncField = function (onFieldChanged: string | FieldChangedCallbackFn | undefined | null = null) {
 

package/src/engine/engine_physics.ts

@@ -4,14 +4,18 @@ import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
 import type { ComputeBVHOptions, GeometryBVH, MeshBVH, StaticGeometryGenerator } from 'three-mesh-bvh';
 import type { GenerateMeshBVHWorker } from 'three-mesh-bvh/src/workers/GenerateMeshBVHWorker.js';
 
+import type { Collider } from '../engine-components/Collider.js';
+import type { Rigidbody } from '../engine-components/RigidBody.js';
 import { isDevEnvironment } from './debug/index.js';
 import { Gizmos } from './engine_gizmos.js';
+import type { RapierPhysics } from './engine_physics_rapier.js';
 import { Context } from './engine_setup.js';
 import { getTempVector, getWorldPosition } from "./engine_three_utils.js"
 import type { ConstructorConcrete, Vec2, Vec3, } from './engine_types.js';
 import type { IPhysicsEngine } from './engine_types.js';
 import { getParam } from "./engine_utils.js"
 
+
 const debugPhysics = getParam("debugphysics");
 const debugWorker = getParam("debugworker");
 const layerMaskHelper: Layers = new Layers();
@@ -133,11 +137,47 @@ export class SphereIntersection implements Intersection {
     }
 }
 
+/**
+ * Provides physics utilities including raycasting and overlap detection.  
+ * Access via `this.context.physics` from any component.  
+ *
+ * For physics engine features (rigidbodies, colliders, forces, etc.), use `this.context.physics.engine`.  
+ * The physics engine is {@link RapierPhysics}, which uses the Rapier physics library for realistic simulation.  
+ *
+ * **Performance - Automatic MeshBVH:**
+ * Needle Engine automatically uses [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh) to accelerate raycasting.  
+ * MeshBVH structures are generated automatically on web workers in the background, making raycasts significantly faster  
+ * without blocking the main thread. This happens transparently - you don't need to do anything to enable it.  
+ * While the BVH is being generated, raycasts fall back to standard three.js raycasting (configurable via `allowSlowRaycastFallback`).  
+ *
+ * @example Raycasting from mouse position
+ * ```ts
+ * const hits = this.context.physics.raycast();
+ * if (hits.length > 0) {
+ *   console.log("Hit:", hits[0].object.name);
+ * }
+ * ```
+ * @example Raycasting with inline options
+ * ```ts
+ * const hits = this.context.physics.raycast({
+ *   maxDistance: 100, // Only hit objects within 100 units
+ *   layerMask: 1, // Only layer 0
+ *   ignore: [this.gameObject] // Ignore self
+ * });
+ * ```
+ * @example Physics engine raycast (against colliders only)
+ * ```ts
+ * const hit = this.context.physics.engine?.raycast(origin, direction);
+ * ```
+ * @see {@link Rigidbody} for physics simulation component
+ * @see {@link Collider} for collision detection component
+ * @see {@link RapierPhysics} for physics engine implementation details
+ */
 export class Physics {
 
     private static _raycasting: number = 0;
     /**
-     * Returns true if raycasting is currently happening
+     * Returns true if raycasting is currently in progress
      */
     public static get raycasting() {
         return this._raycasting > 0;

package/src/engine/engine_physics_rapier.ts

@@ -3,13 +3,16 @@ import { BufferAttribute, BufferGeometry, InterleavedBufferAttribute, LineBasicM
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 
 import { CollisionDetectionMode, PhysicsMaterialCombine } from '../engine/engine_physics.types.js';
+import type { Collider as NeedleCollider } from '../engine-components/Collider.js';
 import { MeshCollider } from '../engine-components/Collider.js';
+import type { Rigidbody as NeedleRigidbody } from '../engine-components/RigidBody.js';
 import { isDevEnvironment } from './debug/debug.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { foreachComponent } from './engine_gameobject.js';
 import { Gizmos } from './engine_gizmos.js';
 import { Mathf } from './engine_math.js';
 import { MODULES } from './engine_modules.js';
+import type { Physics } from './engine_physics.js';
 import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPositionXYZ, setWorldQuaternionXYZW } from "./engine_three_utils.js"
 import type {
     IBoxCollider,
@@ -61,6 +64,84 @@ declare type PhysicsBody = {
     rotation(): { x: number, y: number, z: number, w: number }
 }
 
+/**
+ * Rapier physics engine implementation for Needle Engine.  
+ *
+ * Rapier is a fast, cross-platform physics engine that provides realistic physics simulation  
+ * for rigidbodies, colliders, joints, and collision detection. It runs entirely in WebAssembly  
+ * for high performance.  
+ *
+ * **Features:**  
+ * - Rigidbody simulation (dynamic, kinematic, static)  
+ * - Multiple collider shapes (box, sphere, capsule, mesh, convex hull)  
+ * - Raycasting and shape overlap queries against physics colliders  
+ * - Collision and trigger events  
+ * - Joints (fixed, hinge, etc.)  
+ * - Continuous collision detection (CCD)  
+ * - Physics materials (friction, bounciness)  
+ *
+ * **Access:**  
+ * The Rapier physics engine is accessible via `this.context.physics.engine` from any component.  
+ * Rapier is automatically initialized when physics components are used.  
+ *
+ * **Using the Rapier Module Directly:**  
+ * Rapier is lazy-loaded for performance. You can access the raw Rapier module via {@link MODULES.RAPIER_PHYSICS}.  
+ * Use `MODULES.RAPIER_PHYSICS.load()` to load the module, or `MODULES.RAPIER_PHYSICS.ready()` to wait for it without triggering a load.  
+ * Once loaded, the module is available at `MODULES.RAPIER_PHYSICS.MODULE`.  
+ *
+ * **Note:**  
+ * This is the low-level physics engine implementation. For general raycasting (against all scene objects),  
+ * use {@link Physics.raycast} instead. Use this class for physics-specific operations like applying forces,  
+ * raycasting against colliders only, or accessing the Rapier world directly.  
+ *
+ * @example Applying forces to a rigidbody  
+ * ```ts
+ * const rb = this.gameObject.getComponent(Rigidbody);
+ * if (rb) {
+ *   this.context.physics.engine?.addForce(rb, { x: 0, y: 10, z: 0 }, true);
+ * }
+ * ```
+ * @example Raycasting against physics colliders only  
+ * ```ts
+ * const origin = { x: 0, y: 5, z: 0 };
+ * const direction = { x: 0, y: -1, z: 0 };
+ * const hit = this.context.physics.engine?.raycast(origin, direction);
+ * if (hit) {
+ *   console.log("Hit collider:", hit.collider.name);
+ * }
+ * ```
+ * @example Accessing Rapier world directly  
+ * ```ts
+ * const rapierWorld = this.context.physics.engine?.world;
+ * if (rapierWorld) {
+ *   // Direct access to Rapier API
+ *   console.log("Gravity:", rapierWorld.gravity);
+ * }
+ * ```
+ * @example Using the Rapier module directly  
+ * ```ts
+ * import { MODULES } from "@needle-tools/engine";
+ *
+ * // Load the Rapier module
+ * const RAPIER = await MODULES.RAPIER_PHYSICS.load();
+ *
+ * // Now you can use Rapier types and create custom physics objects
+ * const rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic()
+ *   .setTranslation(0, 10, 0);
+ *
+ * // Or access the already-loaded module
+ * if (MODULES.RAPIER_PHYSICS.MODULE) {
+ *   const colliderDesc = MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.ball(1.0);
+ * }
+ * ```
+ * @see {@link Rigidbody} for physics simulation component
+ * @see {@link Collider} for collision detection component
+ * @see {@link Physics} for general raycasting and physics utilities
+ * @see {@link MODULES.RAPIER_PHYSICS} for direct access to the Rapier module
+ * @link https://rapier.rs/docs/ for Rapier documentation
+ * @link https://engine.needle.tools/docs/reference/components.html#physics
+ * @link https://engine.needle.tools/docs/how-to-guides/scripting/use-physics.html
+ */
 export class RapierPhysics implements IPhysicsEngine {
 
     debugRenderColliders: boolean = false;

package/src/engine/engine_serialization_decorator.ts

@@ -8,8 +8,34 @@ export const serializeable = function <T>(type?: Constructor<T> | null | Array<C
 }
 
 /**
- * The serializable attribute should be used to annotate all serialized fields / fields and members that should be serialized and exposed in an editor
- * @param type The type of the field. If not provided the type will be inferred from the constructor of the field. If the field is a primitive type (string, number, boolean) the type should be null.  
+ * Marks a field for serialization and editor exposure. Required for fields that reference  
+ * other objects, components, or assets. Primitive types (string, number, boolean) work without a type argument.  
+ *
+ * @param type The constructor type for complex objects. Omit for primitives.
+ *
+ * @example Primitive types (no type needed)
+ * ```ts
+ * @serializable()
+ * speed: number = 1;
+ *
+ * @serializable()
+ * label: string = "Hello";
+ * ```
+ * @example Object references
+ * ```ts
+ * @serializable(Object3D)
+ * target: Object3D | null = null;
+ *
+ * @serializable(Renderer)
+ * myRenderer: Renderer | null = null;
+ * ```
+ * @example Arrays
+ * ```ts
+ * @serializable([Object3D])
+ * waypoints: Object3D[] = [];
+ * ```
+ * @see {@link syncField} for automatic network synchronization
+ * @link https://engine.needle.tools/docs/reference/typescript-decorators.html#serializable
  */
 export const serializable = function <T>(type?: Constructor<T> | null | Array<Constructor<any> | TypeResolver<T>> | TypeResolver<T>) {
     if (type === undefined) type = null;

package/src/engine/engine_time.ts

@@ -8,8 +8,23 @@ let timeScale = 1;
 if (typeof timescaleUrl === "number") timeScale = timescaleUrl;
 
 /**
- * Time is a class that provides time-related information.  
- * It is created and used within the Needle Engine Context.
+ * Provides time-related information for frame-based game logic.  
+ * Access via `this.context.time` from any component.  
+ *
+ * @example Using deltaTime for frame-rate independent movement
+ * ```ts
+ * update() {
+ *   // Move 1 unit per second regardless of frame rate
+ *   this.gameObject.position.x += 1 * this.context.time.deltaTime;
+ * }
+ * ```
+ * @example Checking elapsed time
+ * ```ts
+ * start() {
+ *   console.log(`Time since start: ${this.context.time.time}s`);
+ *   console.log(`Current frame: ${this.context.time.frameCount}`);
+ * }
+ * ```
  */
 export class Time implements ITime {
 
@@ -27,7 +42,12 @@ export class Time implements ITime {
     get deltaTimeUnscaled() { return this._deltaTimeUnscaled; }
     private _deltaTimeUnscaled = 0;
 
-    /** The scale at which time passes. This can be used for slow motion effects or to speed up time. */
+    /**
+     * The scale at which time passes. Default is 1.
+     * - Values < 1 create slow motion (e.g. 0.5 = half speed)
+     * - Values > 1 speed up time (e.g. 2 = double speed)
+     * - Value of 0 effectively pauses time-dependent logic
+     */
     timeScale = 1;
 
     /** same as frameCount */

package/src/engine/engine_util_decorator.ts

@@ -9,7 +9,37 @@ import { watchWrite } from "./engine_utils.js";
 declare type setter = (v: any) => void;
 declare type getter = () => any;
 
-/** create accessor callbacks for a field */
+/**
+ * Marks a field to trigger the `onValidate` callback when its value changes.  
+ * Useful for reacting to property changes from the editor or at runtime.  
+ *
+ * Your component must implement `onValidate(property?: string)` to receive notifications.  
+ *
+ * @param set Optional custom setter called before the value is assigned
+ * @param get Optional custom getter called when the value is read
+ *
+ * @example Basic usage
+ * ```ts
+ * export class MyComponent extends Behaviour {
+ *   @serializable()
+ *   @validate()
+ *   color: Color = new Color(1, 0, 0);
+ *
+ *   onValidate(property?: string) {
+ *     if (property === "color") {
+ *       console.log("Color changed to:", this.color);
+ *     }
+ *   }
+ * }
+ * ```
+ * @example With custom setter
+ * ```ts
+ * @validate(function(value) {
+ *   console.log("Setting speed to", value);
+ * })
+ * speed: number = 1;
+ * ```
+ */
 export const validate = function (set?: setter, get?: getter) {
     // "descriptor : undefined" prevents @validate() to be added to property getters or setters
     return function (target: IComponent | any, propertyKey: string, descriptor?: undefined) {