@dcl/protocol 1.0.0-34848312390.commit-ca008c2 → 1.0.0-34875307214.commit-1ca8fa7

package/out-ts/decentraland/sdk/components/ui_scroll_result.gen.ts

@@ -0,0 +1,83 @@
+/* eslint-disable */
+import _m0 from "protobufjs/minimal";
+import { Vector2 } from "../../common/vectors.gen";
+
+export const protobufPackage = "decentraland.sdk.components";
+
+export interface PBUiScrollResult {
+  value: Vector2 | undefined;
+}
+
+function createBasePBUiScrollResult(): PBUiScrollResult {
+  return { value: undefined };
+}
+
+export namespace PBUiScrollResult {
+  export function encode(message: PBUiScrollResult, writer: _m0.Writer = _m0.Writer.create()): _m0.Writer {
+    if (message.value !== undefined) {
+      Vector2.encode(message.value, writer.uint32(10).fork()).ldelim();
+    }
+    return writer;
+  }
+
+  export function decode(input: _m0.Reader | Uint8Array, length?: number): PBUiScrollResult {
+    const reader = input instanceof _m0.Reader ? input : _m0.Reader.create(input);
+    let end = length === undefined ? reader.len : reader.pos + length;
+    const message = createBasePBUiScrollResult();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1:
+          if (tag !== 10) {
+            break;
+          }
+
+          message.value = Vector2.decode(reader, reader.uint32());
+          continue;
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skipType(tag & 7);
+    }
+    return message;
+  }
+
+  export function fromJSON(object: any): PBUiScrollResult {
+    return { value: isSet(object.value) ? Vector2.fromJSON(object.value) : undefined };
+  }
+
+  export function toJSON(message: PBUiScrollResult): unknown {
+    const obj: any = {};
+    message.value !== undefined && (obj.value = message.value ? Vector2.toJSON(message.value) : undefined);
+    return obj;
+  }
+
+  export function create<I extends Exact<DeepPartial<PBUiScrollResult>, I>>(base?: I): PBUiScrollResult {
+    return PBUiScrollResult.fromPartial(base ?? {});
+  }
+
+  export function fromPartial<I extends Exact<DeepPartial<PBUiScrollResult>, I>>(object: I): PBUiScrollResult {
+    const message = createBasePBUiScrollResult();
+    message.value = (object.value !== undefined && object.value !== null)
+      ? Vector2.fromPartial(object.value)
+      : undefined;
+    return message;
+  }
+}
+
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+
+export type DeepPartial<T> = T extends Builtin ? T
+  : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>>
+  : T extends { $case: string } ? { [K in keyof Omit<T, "$case">]?: DeepPartial<T[K]> } & { $case: T["$case"] }
+  : T extends {} ? { [K in keyof T]?: DeepPartial<T[K]> }
+  : Partial<T>;
+
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P
+  : P & { [K in keyof P]: Exact<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion<P>>]: never };
+
+function isSet(value: any): boolean {
+  return value !== null && value !== undefined;
+}

package/out-ts/decentraland/sdk/components/ui_text.gen.ts

@@ -65,7 +65,11 @@ export interface PBUiText {
     | number
     | undefined;
   /** wrap text when the border is reached (default: TW_WRAP) */
-  textWrap?: TextWrap | undefined;
+  textWrap?:
+    | TextWrap
+    | undefined;
+  /** a font file in the scene, or a Google Fonts family name; `font` is the fallback (default: unset) */
+  fontSrc?: string | undefined;
 }
 
 function createBasePBUiText(): PBUiText {
@@ -76,6 +80,7 @@ function createBasePBUiText(): PBUiText {
     font: undefined,
     fontSize: undefined,
     textWrap: undefined,
+    fontSrc: undefined,
   };
 }
 
@@ -99,6 +104,9 @@ export namespace PBUiText {
     if (message.textWrap !== undefined) {
       writer.uint32(48).int32(message.textWrap);
     }
+    if (message.fontSrc !== undefined) {
+      writer.uint32(74).string(message.fontSrc);
+    }
     return writer;
   }
 
@@ -151,6 +159,13 @@ export namespace PBUiText {
 
           message.textWrap = reader.int32() as any;
           continue;
+        case 9:
+          if (tag !== 74) {
+            break;
+          }
+
+          message.fontSrc = reader.string();
+          continue;
       }
       if ((tag & 7) === 4 || tag === 0) {
         break;
@@ -168,6 +183,7 @@ export namespace PBUiText {
       font: isSet(object.font) ? fontFromJSON(object.font) : undefined,
       fontSize: isSet(object.fontSize) ? Number(object.fontSize) : undefined,
       textWrap: isSet(object.textWrap) ? textWrapFromJSON(object.textWrap) : undefined,
+      fontSrc: isSet(object.fontSrc) ? String(object.fontSrc) : undefined,
     };
   }
 
@@ -181,6 +197,7 @@ export namespace PBUiText {
     message.fontSize !== undefined && (obj.fontSize = Math.round(message.fontSize));
     message.textWrap !== undefined &&
       (obj.textWrap = message.textWrap !== undefined ? textWrapToJSON(message.textWrap) : undefined);
+    message.fontSrc !== undefined && (obj.fontSrc = message.fontSrc);
     return obj;
   }
 
@@ -198,6 +215,7 @@ export namespace PBUiText {
     message.font = object.font ?? undefined;
     message.fontSize = object.fontSize ?? undefined;
     message.textWrap = object.textWrap ?? undefined;
+    message.fontSrc = object.fontSrc ?? undefined;
     return message;
   }
 }

package/out-ts/decentraland/sdk/components/ui_transform.gen.ts

@@ -1,6 +1,7 @@
 /* eslint-disable */
 import _m0 from "protobufjs/minimal";
 import { Color4 } from "../../common/colors.gen";
+import { Vector2 } from "../../common/vectors.gen";
 
 export const protobufPackage = "decentraland.sdk.components";
 
@@ -472,6 +473,55 @@ export function pointerFilterModeToJSON(object: PointerFilterMode): string {
   }
 }
 
+export enum ShowScrollBar {
+  SSB_BOTH = 0,
+  SSB_ONLY_VERTICAL = 1,
+  SSB_ONLY_HORIZONTAL = 2,
+  SSB_HIDDEN = 3,
+  UNRECOGNIZED = -1,
+}
+
+export function showScrollBarFromJSON(object: any): ShowScrollBar {
+  switch (object) {
+    case 0:
+    case "SSB_BOTH":
+      return ShowScrollBar.SSB_BOTH;
+    case 1:
+    case "SSB_ONLY_VERTICAL":
+      return ShowScrollBar.SSB_ONLY_VERTICAL;
+    case 2:
+    case "SSB_ONLY_HORIZONTAL":
+      return ShowScrollBar.SSB_ONLY_HORIZONTAL;
+    case 3:
+    case "SSB_HIDDEN":
+      return ShowScrollBar.SSB_HIDDEN;
+    case -1:
+    case "UNRECOGNIZED":
+    default:
+      return ShowScrollBar.UNRECOGNIZED;
+  }
+}
+
+export function showScrollBarToJSON(object: ShowScrollBar): string {
+  switch (object) {
+    case ShowScrollBar.SSB_BOTH:
+      return "SSB_BOTH";
+    case ShowScrollBar.SSB_ONLY_VERTICAL:
+      return "SSB_ONLY_VERTICAL";
+    case ShowScrollBar.SSB_ONLY_HORIZONTAL:
+      return "SSB_ONLY_HORIZONTAL";
+    case ShowScrollBar.SSB_HIDDEN:
+      return "SSB_HIDDEN";
+    case ShowScrollBar.UNRECOGNIZED:
+    default:
+      return "UNRECOGNIZED";
+  }
+}
+
+export interface ScrollPositionValue {
+  value?: { $case: "position"; position: Vector2 } | { $case: "reference"; reference: string } | undefined;
+}
+
 export interface PBUiTransform {
   parent: number;
   rightOf: number;
@@ -616,10 +666,105 @@ export interface PBUiTransform {
   opacity?:
     | number
     | undefined;
+  /** reference for scroll_position. default empty */
+  elementId?:
+    | string
+    | undefined;
+  /** default position=(0,0) */
+  scrollPosition?:
+    | ScrollPositionValue
+    | undefined;
+  /** default ShowScrollBar.SSB_BOTH */
+  scrollVisible?:
+    | ShowScrollBar
+    | undefined;
   /** default: 0 — controls render stacking order. Higher values appear in front of lower values. */
   zIndex?: number | undefined;
 }
 
+function createBaseScrollPositionValue(): ScrollPositionValue {
+  return { value: undefined };
+}
+
+export namespace ScrollPositionValue {
+  export function encode(message: ScrollPositionValue, writer: _m0.Writer = _m0.Writer.create()): _m0.Writer {
+    switch (message.value?.$case) {
+      case "position":
+        Vector2.encode(message.value.position, writer.uint32(10).fork()).ldelim();
+        break;
+      case "reference":
+        writer.uint32(18).string(message.value.reference);
+        break;
+    }
+    return writer;
+  }
+
+  export function decode(input: _m0.Reader | Uint8Array, length?: number): ScrollPositionValue {
+    const reader = input instanceof _m0.Reader ? input : _m0.Reader.create(input);
+    let end = length === undefined ? reader.len : reader.pos + length;
+    const message = createBaseScrollPositionValue();
+    while (reader.pos < end) {
+      const tag = reader.uint32();
+      switch (tag >>> 3) {
+        case 1:
+          if (tag !== 10) {
+            break;
+          }
+
+          message.value = { $case: "position", position: Vector2.decode(reader, reader.uint32()) };
+          continue;
+        case 2:
+          if (tag !== 18) {
+            break;
+          }
+
+          message.value = { $case: "reference", reference: reader.string() };
+          continue;
+      }
+      if ((tag & 7) === 4 || tag === 0) {
+        break;
+      }
+      reader.skipType(tag & 7);
+    }
+    return message;
+  }
+
+  export function fromJSON(object: any): ScrollPositionValue {
+    return {
+      value: isSet(object.position)
+        ? { $case: "position", position: Vector2.fromJSON(object.position) }
+        : isSet(object.reference)
+        ? { $case: "reference", reference: String(object.reference) }
+        : undefined,
+    };
+  }
+
+  export function toJSON(message: ScrollPositionValue): unknown {
+    const obj: any = {};
+    message.value?.$case === "position" &&
+      (obj.position = message.value?.position ? Vector2.toJSON(message.value?.position) : undefined);
+    message.value?.$case === "reference" && (obj.reference = message.value?.reference);
+    return obj;
+  }
+
+  export function create<I extends Exact<DeepPartial<ScrollPositionValue>, I>>(base?: I): ScrollPositionValue {
+    return ScrollPositionValue.fromPartial(base ?? {});
+  }
+
+  export function fromPartial<I extends Exact<DeepPartial<ScrollPositionValue>, I>>(object: I): ScrollPositionValue {
+    const message = createBaseScrollPositionValue();
+    if (object.value?.$case === "position" && object.value?.position !== undefined && object.value?.position !== null) {
+      message.value = { $case: "position", position: Vector2.fromPartial(object.value.position) };
+    }
+    if (
+      object.value?.$case === "reference" && object.value?.reference !== undefined && object.value?.reference !== null
+    ) {
+      message.value = { $case: "reference", reference: object.value.reference };
+    }
+    return message;
+  }
+}
+
 function createBasePBUiTransform(): PBUiTransform {
   return {
     parent: 0,
@@ -695,6 +840,9 @@ function createBasePBUiTransform(): PBUiTransform {
     borderLeftColor: undefined,
     borderRightColor: undefined,
     opacity: undefined,
+    elementId: undefined,
+    scrollPosition: undefined,
+    scrollVisible: undefined,
     zIndex: undefined,
   };
 }
@@ -920,6 +1068,15 @@ export namespace PBUiTransform {
     if (message.opacity !== undefined) {
       writer.uint32(589).float(message.opacity);
     }
+    if (message.elementId !== undefined) {
+      writer.uint32(594).string(message.elementId);
+    }
+    if (message.scrollPosition !== undefined) {
+      ScrollPositionValue.encode(message.scrollPosition, writer.uint32(602).fork()).ldelim();
+    }
+    if (message.scrollVisible !== undefined) {
+      writer.uint32(608).int32(message.scrollVisible);
+    }
     if (message.zIndex !== undefined) {
       writer.uint32(616).int32(message.zIndex);
     }
@@ -1444,6 +1601,27 @@ export namespace PBUiTransform {
 
           message.opacity = reader.float();
           continue;
+        case 74:
+          if (tag !== 594) {
+            break;
+          }
+
+          message.elementId = reader.string();
+          continue;
+        case 75:
+          if (tag !== 602) {
+            break;
+          }
+
+          message.scrollPosition = ScrollPositionValue.decode(reader, reader.uint32());
+          continue;
+        case 76:
+          if (tag !== 608) {
+            break;
+          }
+
+          message.scrollVisible = reader.int32() as any;
+          continue;
         case 77:
           if (tag !== 616) {
             break;
@@ -1549,6 +1727,9 @@ export namespace PBUiTransform {
       borderLeftColor: isSet(object.borderLeftColor) ? Color4.fromJSON(object.borderLeftColor) : undefined,
       borderRightColor: isSet(object.borderRightColor) ? Color4.fromJSON(object.borderRightColor) : undefined,
       opacity: isSet(object.opacity) ? Number(object.opacity) : undefined,
+      elementId: isSet(object.elementId) ? String(object.elementId) : undefined,
+      scrollPosition: isSet(object.scrollPosition) ? ScrollPositionValue.fromJSON(object.scrollPosition) : undefined,
+      scrollVisible: isSet(object.scrollVisible) ? showScrollBarFromJSON(object.scrollVisible) : undefined,
       zIndex: isSet(object.zIndex) ? Number(object.zIndex) : undefined,
     };
   }
@@ -1662,6 +1843,13 @@ export namespace PBUiTransform {
     message.borderRightColor !== undefined &&
       (obj.borderRightColor = message.borderRightColor ? Color4.toJSON(message.borderRightColor) : undefined);
     message.opacity !== undefined && (obj.opacity = message.opacity);
+    message.elementId !== undefined && (obj.elementId = message.elementId);
+    message.scrollPosition !== undefined &&
+      (obj.scrollPosition = message.scrollPosition ? ScrollPositionValue.toJSON(message.scrollPosition) : undefined);
+    message.scrollVisible !== undefined &&
+      (obj.scrollVisible = message.scrollVisible !== undefined
+        ? showScrollBarToJSON(message.scrollVisible)
+        : undefined);
     message.zIndex !== undefined && (obj.zIndex = Math.round(message.zIndex));
     return obj;
   }
@@ -1753,6 +1941,11 @@ export namespace PBUiTransform {
       ? Color4.fromPartial(object.borderRightColor)
       : undefined;
     message.opacity = object.opacity ?? undefined;
+    message.elementId = object.elementId ?? undefined;
+    message.scrollPosition = (object.scrollPosition !== undefined && object.scrollPosition !== null)
+      ? ScrollPositionValue.fromPartial(object.scrollPosition)
+      : undefined;
+    message.scrollVisible = object.scrollVisible ?? undefined;
     message.zIndex = object.zIndex ?? undefined;
     return message;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl/protocol",
-  "version": "1.0.0-34848312390.commit-ca008c2",
+  "version": "1.0.0-34875307214.commit-1ca8fa7",
   "description": "",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
     "gen:test": "node protoc-gen-bitwise/test/generator.test.js"
   },
   "devDependencies": {
-    "@protobuf-ts/protoc": "^2.11.0",
+    "@protobuf-ts/protoc": "^2.8.1",
     "proto-compatibility-tool": "^1.1.2-20220925163655.commit-25bd040",
     "typescript": "^5.0.4"
   },
@@ -36,5 +36,5 @@
     "protoc-gen-bitwise/*.js",
     "protoc-gen-bitwise/runtime"
   ],
-  "commit": "ca008c24e955c08a8fffea434fd79c7b943ef8ec"
+  "commit": "1ca8fa7b4ec3342df3ef12421ec61558f86bf76f"
 }

package/proto/decentraland/common/texture.proto

@@ -36,10 +36,17 @@ message VideoTexture {
   optional TextureFilterMode filter_mode = 3; // default = FilterMode.Bilinear
 }
 
+message UiCanvasTexture {
+  uint32 ui_canvas_entity = 1;
+  optional TextureWrapMode wrap_mode = 2; // default = TextureWrapMode.Clamp
+  optional TextureFilterMode filter_mode = 3; // default = FilterMode.Bilinear
+}
+
 message TextureUnion {
   oneof tex {
     Texture texture = 1; // default = null
     AvatarTexture avatar_texture = 2; // default = null
     VideoTexture video_texture = 3; // default = null
+    UiCanvasTexture ui_texture = 4;
   }
-}
+}

package/proto/decentraland/kernel/apis/restricted_actions.proto

@@ -61,8 +61,31 @@ message MovePlayerToResponse {
   bool success = 1;
 }
 
+message WalkPlayerToRequest {
+  decentraland.common.Vector3 new_relative_position = 1;
+  float stop_threshold = 2;
+  optional float timeout = 3; // max seconds before the request is failed; not passed to the movement scene
+}
+
+message WalkPlayerToResponse {
+  bool success = 1;
+}
+
 message TeleportToResponse { }
 
+message SetUiFocusRequest {
+  string element_id = 1;
+}
+
+message ClearUiFocusRequest { }
+
+message GetUiFocusRequest { }
+
+message UiFocusResponse {
+  // the element that is/was focussed
+  optional string element_id = 1;
+}
+
 message CopyToClipboardRequest {
   string text = 1;
 }
@@ -75,7 +98,7 @@ message StopEmoteRequest { }
 enum OpenExplorerUiResult {
   UNSPECIFIED = 0;
   OPENED = 1;
-  WAS_ALREADY_OPEN = 2;             // the slot the requested panel occupies is already in use; panels sharing a slot exclude each other
+  WAS_ALREADY_OPEN = 2;             // a fullscreen panel is already open
   REJECTED_NOT_CURRENT_SCENE = 3;   // the standard restricted-actions current-scene gate rejected the call
   REJECTED_FEATURE_DISABLED = 4;    // the requested section is hidden by feature flags or client doesn't have that feature
   REJECTED_NO_USER_GESTURE = 5;     // rejected: the call did not originate from a user gesture
@@ -83,17 +106,11 @@ enum OpenExplorerUiResult {
 
 message OpenExplorerUiRequest {
   decentraland.sdk.components.common.ExplorerUi ui = 1;
-  // Echoed back in the events this request produces, so they can be matched to their call.
-  // Unset means no correlation, and 0 is reserved for the same meaning on the result, so ids start at 1.
-  optional uint32 request_id = 2;
-
-  message ItemPurchaseParams {
-    string urn = 1;
-  }
 
-  oneof params {
-    ItemPurchaseParams item_purchase = 10;
-  }
+  // Extension point for future per-panel parameters, as a oneof so each panel gets its
+  // own optional param message without touching existing fields. 
+  //   message MapParams { int32 focus_x = 1; int32 focus_y = 2; }
+  //   oneof params { MapParams map = 10; }
 }
 
 message OpenExplorerUiResponse {
@@ -108,6 +125,12 @@ service RestrictedActionsService {
   rpc MovePlayerTo(MovePlayerToRequest) returns (MovePlayerToResponse) {}
 
   // TeleportTo will move the user to the specified world LAND parcel coordinates
+  // WalkPlayerTo will walk the player to a position relative to the current scene,
+  // managed by the movement controller scene. Returns success when the player reaches
+  // within stop_threshold distance, or false if the path is blocked, the player gets
+  // stuck, the player interrupts the walk with manual input, or the optional timeout expires.
+  rpc WalkPlayerTo(WalkPlayerToRequest) returns (WalkPlayerToResponse) {}
+
   rpc TeleportTo(TeleportToRequest) returns (TeleportToResponse) {}
 
   // TriggerEmote will trigger an emote in this current user
@@ -131,11 +154,20 @@ service RestrictedActionsService {
   rpc TriggerSceneEmote(TriggerSceneEmoteRequest) returns (SuccessResponse) {}
 
   // CopyToClipboard copies the provided text into the clipboard
+  // Sets the focus to a specific UI element
+  rpc SetUiFocus(SetUiFocusRequest) returns (UiFocusResponse) {}
+
+  // Clears the focus from any currently focused textentry or dropdown
+  rpc ClearUiFocus(ClearUiFocusRequest) returns (UiFocusResponse) {}
+
+  // Returns the element_id of any currently focused textentry or dropdown
+  rpc GetUiFocus(GetUiFocusRequest) returns (UiFocusResponse) {}
+
   rpc CopyToClipboard(CopyToClipboardRequest) returns (EmptyResponse) {}
 
   // StopEmote will stop the current emote
   rpc StopEmote(StopEmoteRequest) returns (SuccessResponse) {}
 
-  // OpenExplorerUi opens an explorer panel, fullscreen or modal, and returns the open verdict.
+  // OpenExplorerUi opens a specific fullscreen explorer panel and returns the open verdict.
   rpc OpenExplorerUi(OpenExplorerUiRequest) returns (OpenExplorerUiResponse) {}
 }

package/proto/decentraland/kernel/comms/rfc4/comms.proto

@@ -94,14 +94,6 @@ message PlayerEmote {
   uint32 incremental_id = 1;
   string urn = 2;
   float timestamp = 3;
-  optional bool is_stopping = 4; // true means the emote has been stopped in the sender's client
-  optional bool is_repeating = 5; // true when it is not the first time the looping animation plays
-  optional int32 interaction_id = 6; // identifies an interaction univocaly, established when the start animation is triggered
-  optional int32 social_emote_outcome = 7; // -1 means it does not use an outcome animation
-  optional bool is_reacting = 8; // to a social emote started by other user
-  optional string social_emote_initiator = 9; // wallet address of the user that initiated social emote
-  optional string target_avatar = 10; // wallet address of the user whose avatar is the target of a directed emote
-  optional uint32 mask = 11; // mask for which bones an animation applies to.
 }
 
 message SceneEmote {
@@ -134,9 +126,6 @@ message ProfileResponse {
 message Chat {
   string message = 1;
   double timestamp = 2;
-  // Extension: optional forwarded_from to identify the original sender when
-  // messages are forwarded through an SFU
-  optional string forwarded_from = 3;
 }
 
 message Scene {

package/proto/decentraland/sdk/components/avatar_equipped_data.proto

@@ -10,4 +10,5 @@ option (common.ecs_component_id) = 1091;
 message PBAvatarEquippedData {
   repeated string wearable_urns = 1;
   repeated string emote_urns = 2;
-}
+  repeated string force_render = 3; // slots that will render even if hidden
+}

package/proto/decentraland/sdk/components/avatar_modifier_area.proto

@@ -23,6 +23,7 @@ message PBAvatarModifierArea {
   decentraland.common.Vector3 area = 1;      // the 3D size of the region
   repeated string exclude_ids = 2;           // user IDs that can enter and remain unaffected
   repeated AvatarModifierType modifiers = 3; // list of modifiers to apply
+  optional bool use_collider_range = 5;      // if true, the player will be considered inside the area when they are within 0.3m of the area. default true
 }
 
 // AvatarModifierType is an effect that should be applied to avatars inside the region.

package/proto/decentraland/sdk/components/avatar_movement.proto

@@ -0,0 +1,62 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/sdk/components/common/id.proto";
+import "decentraland/common/vectors.proto";
+
+option (common.ecs_component_id) = 1501;
+
+message PBAvatarMovement {
+  decentraland.common.Vector3 velocity = 1;
+  float orientation = 2;                                    // 0-360, yaw only; this is the authoritative facing (other clients read it, and physics treats the avatar as upright). Lean is expressed separately via tilt_pitch/tilt_roll.
+  optional decentraland.common.Vector3 ground_direction = 3;
+  optional bool walk_success = 4;                           // set for one frame when a walk_target ends: true = reached target, false = failed; absent = in progress or no walk
+  optional MovementAnimation animation = 5;                 // if set, the engine plays this animation instead of selecting one from velocity heuristics
+  optional float tilt_pitch = 6;                            // render-only forward/back lean in degrees, applied on top of `orientation` (rotation about the avatar's local X axis). Does not affect the physics capsule (stays upright) or the facing other clients read. Defaults to 0.
+  optional float tilt_roll = 7;                             // render-only sideways lean in degrees, applied on top of `orientation` (rotation about the avatar's local Z axis). Same constraints as tilt_pitch. Useful e.g. for glider banking. Defaults to 0.
+}
+
+// Describes the animation the movement scene wants the avatar to play.
+// One GLB = one clip (following the scene-emote convention: single clip, or a clip named with `_Avatar` suffix).
+// When absent the engine falls back to its built-in velocity-based selection (walk/run/jump/idle).
+message MovementAnimation {
+  string src = 1;                                           // scene-relative path to the gltf/glb asset (resolved via the scene content map)
+  bool loop = 2;                                            // whether the clip repeats once it reaches the end
+  float speed = 3;                                          // playback speed multiplier (1.0 = clip's native rate)
+  bool idle = 4;                                            // true: a triggerSceneEmote may take over; false: emotes are suppressed while this animation plays
+  optional float transition_seconds = 5;                    // cross-fade duration when `src` changes; defaults to 0.2 when unset. Not applied to loop/speed/idle changes.
+  optional float playback_time = 6;                         // if set, the engine seeks to this position (in seconds) this frame. Clear on subsequent frames to allow normal playback. The scene can read `AvatarAnimationState.playback_time` first to decide.
+  repeated string sounds = 7;                               // scene-relative paths to audio clips (.mp3/.ogg) to play this frame on the avatar audio bus. Fire-and-forget: each listed clip plays once per frame it appears; leaving a clip set for multiple frames re-triggers it. No stop mechanism. Use `AvatarAnimationState.playback_time` to trigger sounds at the right point in the clip (e.g. foot plants).
+}
+
+// engine behaviour (uses only capsule shapecasts and GJK closest point for portability):
+// 1: set avatar orientation from movement info -> P1
+// 2: record "ground collider" - nearest collider within threshold distance in ground_direction using avatar collider shapecast
+// 3: update all colliders, record previous transform and new transform.
+// 4: apply ground collider movement: take collider closest point, modify P1 translation and rotation by closest point translation and rotation change -> P2
+// 5: resolve collisions using position-based constraints
+//   initialize constraints to -inf, +inf
+//   repeat
+//       for each collider[i] that collides with the P3+N player:
+//           if closest point = capsule middle (i.e. collider collides with P3 collider but with radius 0), 
+//               ignore / continue
+//           else 
+//               update constraints based on minimum movement to escape collision
+//               e.g. if avatar is 1cm into the floor, constraint_min = max(constraint_min, vec3(0, 0.01, 0))
+//       reposition player to satisfy constraints for each axis:
+//           y: satsify floor before ceiling: new position = max(constraint_min, min(constraint_max, current position))
+//           x and z: if squashed, take average, else satisfy the required constraint
+//           if constraint_min > constraint_max then new position = average(constraint_min, constraint_max) 
+//           else new position = clamp(current position, constraint_min, constraint_max)
+//   while position !~= previous position
+// 6: apply velocity (collide and slide)
+//   disable anything we are initially colliding with
+//   shapecast avatar from position to position + velocity * timestep
+//   on impact:
+//       project velocity onto slide plane (standard "Collide & Slide")
+//       velocity = old velocity - (normal * dot(velocity, normal))
+//       repeat continue with residual velocity and residual time
+// 7: provide AvatarMovementInfo values
+//      actual velocity = (final - P3+N) / timestep
+//      external_velocity = (P3+N - P1) / timestep