@rpgjs/server 5.0.0-alpha.16 → 5.0.0-alpha.18

package/dist/index.js

@@ -11298,6 +11298,11 @@ class RpgCommonPlayer {
     this._throughEvent = signal(false);
     this._frequency = signal(0);
     this._frames = signal([]);
+    this.componentsTop = signal(null);
+    this.componentsBottom = signal(null);
+    this.componentsCenter = signal(null);
+    this.componentsLeft = signal(null);
+    this.componentsRight = signal(null);
     this.isConnected = signal(false);
     // Store intended movement direction (not synced, only used locally)
     this._intendedDirection = null;
@@ -11349,10 +11354,10 @@ __decorateClass$3([
   sync()
 ], RpgCommonPlayer.prototype, "type");
 __decorateClass$3([
-  persist()
+  sync()
 ], RpgCommonPlayer.prototype, "x");
 __decorateClass$3([
-  persist()
+  sync()
 ], RpgCommonPlayer.prototype, "y");
 __decorateClass$3([
   sync()
@@ -11423,11 +11428,95 @@ __decorateClass$3([
 __decorateClass$3([
   sync()
 ], RpgCommonPlayer.prototype, "_frames");
+__decorateClass$3([
+  sync()
+], RpgCommonPlayer.prototype, "componentsTop");
+__decorateClass$3([
+  sync()
+], RpgCommonPlayer.prototype, "componentsBottom");
+__decorateClass$3([
+  sync()
+], RpgCommonPlayer.prototype, "componentsCenter");
+__decorateClass$3([
+  sync()
+], RpgCommonPlayer.prototype, "componentsLeft");
+__decorateClass$3([
+  sync()
+], RpgCommonPlayer.prototype, "componentsRight");
 __decorateClass$3([
   connected()
 ], RpgCommonPlayer.prototype, "isConnected");
 
-const _Vector2 = class _Vector2 {
+class RpgShape {
+  /**
+   * Creates a new RpgShape instance
+   * 
+   * @param config - Shape configuration
+   */
+  constructor(config) {
+    this.name = config.name;
+    this.positioning = config.positioning;
+    this.width = config.width;
+    this.height = config.height;
+    this.x = config.x;
+    this.y = config.y;
+    this.properties = config.properties;
+    this._playerOwner = config.playerOwner;
+    this._physicZoneId = config.physicZoneId;
+    this._map = config.map;
+  }
+  /**
+   * Checks if a player is currently inside this shape
+   * 
+   * @param player - The player to check
+   * @returns True if the player is inside the shape
+   * 
+   * @example
+   * ```ts
+   * const shape = player.attachShape("detection", { radius: 100 });
+   * if (shape.playerIsIn(otherPlayer)) {
+   *   console.log("Player detected in zone");
+   * }
+   * ```
+   */
+  playerIsIn(player) {
+    if (!this._map) return false;
+    const zoneManager = this._map.physic.getZoneManager();
+    const entities = zoneManager.getEntitiesInZone(this._physicZoneId);
+    if (!entities || entities.length === 0) return false;
+    const playerEntity = this._map.physic.getEntityByUUID(player.id);
+    if (!playerEntity) return false;
+    return entities.some((entity) => entity.uuid === playerEntity.uuid);
+  }
+  /**
+   * Gets the player that owns this shape
+   * 
+   * Returns the player on which `attachShape()` was called to create this shape.
+   * 
+   * @returns The player owner or undefined if not available
+   * 
+   * @example
+   * ```ts
+   * const shape = player.attachShape("vision", { radius: 150 });
+   * const owner = shape.getPlayerOwner();
+   * console.log(owner?.name); // Player's name
+   * ```
+   */
+  getPlayerOwner() {
+    return this._playerOwner;
+  }
+  /**
+   * Updates the shape's position
+   * 
+   * @internal
+   */
+  _updatePosition(x, y) {
+    this.x = x;
+    this.y = y;
+  }
+}
+
+const _Vector2$1 = class _Vector2 {
   /**
    * Creates a new Vector2
    * 
@@ -11697,10 +11786,10 @@ const _Vector2 = class _Vector2 {
     return `Vector2(${this.x}, ${this.y})`;
   }
 };
-_Vector2.ZERO = new _Vector2(0, 0);
-_Vector2.UNIT_X = new _Vector2(1, 0);
-_Vector2.UNIT_Y = new _Vector2(0, 1);
-let Vector2 = _Vector2;
+_Vector2$1.ZERO = new _Vector2$1(0, 0);
+_Vector2$1.UNIT_X = new _Vector2$1(1, 0);
+_Vector2$1.UNIT_Y = new _Vector2$1(0, 1);
+let Vector2$1 = _Vector2$1;
 
 class AABB {
   /**
@@ -11790,7 +11879,7 @@ class AABB {
    * @returns Center point
    */
   getCenter() {
-    return new Vector2(
+    return new Vector2$1(
       (this.minX + this.maxX) / 2,
       (this.minY + this.maxY) / 2
     );
@@ -11968,20 +12057,20 @@ class AABB {
    * @returns Clamped point
    */
   clamp(point) {
-    return new Vector2(
+    return new Vector2$1(
       Math.max(this.minX, Math.min(this.maxX, point.x)),
       Math.max(this.minY, Math.min(this.maxY, point.y))
     );
   }
 }
 
-var EntityState = /* @__PURE__ */ ((EntityState2) => {
+var EntityState$1 = /* @__PURE__ */ ((EntityState2) => {
   EntityState2[EntityState2["Static"] = 1] = "Static";
   EntityState2[EntityState2["Dynamic"] = 2] = "Dynamic";
   EntityState2[EntityState2["Sleeping"] = 4] = "Sleeping";
   EntityState2[EntityState2["Kinematic"] = 8] = "Kinematic";
   return EntityState2;
-})(EntityState || {});
+})(EntityState$1 || {});
 
 function generateUUID() {
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
@@ -12004,20 +12093,20 @@ class Entity {
   constructor(config = {}) {
     this.lastCardinalDirection = "idle";
     this.uuid = config.uuid ?? generateUUID();
-    if (config.position instanceof Vector2) {
+    if (config.position instanceof Vector2$1) {
       this.position = config.position.clone();
     } else if (config.position) {
-      this.position = new Vector2(config.position.x, config.position.y);
+      this.position = new Vector2$1(config.position.x, config.position.y);
     } else {
-      this.position = new Vector2(0, 0);
+      this.position = new Vector2$1(0, 0);
     }
-    this.currentTile = new Vector2(0, 0);
-    if (config.velocity instanceof Vector2) {
+    this.currentTile = new Vector2$1(0, 0);
+    if (config.velocity instanceof Vector2$1) {
       this.velocity = config.velocity.clone();
     } else if (config.velocity) {
-      this.velocity = new Vector2(config.velocity.x, config.velocity.y);
+      this.velocity = new Vector2$1(config.velocity.x, config.velocity.y);
     } else {
-      this.velocity = new Vector2(0, 0);
+      this.velocity = new Vector2$1(0, 0);
     }
     this.rotation = config.rotation ?? 0;
     this.angularVelocity = config.angularVelocity ?? 0;
@@ -12030,14 +12119,14 @@ class Entity {
       this.capsule = config.capsule;
     }
     this.continuous = config.continuous ?? false;
-    this.state = config.state ?? EntityState.Dynamic;
+    this.state = config.state ?? EntityState$1.Dynamic;
     this.restitution = config.restitution ?? 0.2;
     this.friction = config.friction ?? 0.3;
     this.linearDamping = config.linearDamping ?? 0.01;
     this.angularDamping = config.angularDamping ?? 0.01;
     this.maxLinearVelocity = config.maxLinearVelocity ?? Infinity;
     this.maxAngularVelocity = config.maxAngularVelocity ?? Infinity;
-    this.force = new Vector2(0, 0);
+    this.force = new Vector2$1(0, 0);
     this.torque = 0;
     this.collisionMask = config.collisionMask ?? 4294967295;
     this.collisionCategory = config.collisionCategory ?? 1;
@@ -12172,7 +12261,7 @@ class Entity {
    */
   notifyDirectionChange() {
     const isMoving = this.velocity.lengthSquared() > DIRECTION_CHANGE_THRESHOLD_SQ;
-    const direction = isMoving ? this.velocity.clone().normalize() : new Vector2(0, 0);
+    const direction = isMoving ? this.velocity.clone().normalize() : new Vector2$1(0, 0);
     const cardinalDirection = this.computeCardinalDirection(direction);
     if (cardinalDirection !== "idle") {
       this.lastCardinalDirection = cardinalDirection;
@@ -12415,7 +12504,7 @@ class Entity {
    * @returns This entity for chaining
    */
   teleport(position) {
-    if (position instanceof Vector2) {
+    if (position instanceof Vector2$1) {
       this.position.copyFrom(position);
     } else {
       this.position.set(position.x, position.y);
@@ -12432,14 +12521,14 @@ class Entity {
    */
   setVelocity(velocity) {
     const oldVelocity = this.velocity.clone();
-    if (velocity instanceof Vector2) {
+    if (velocity instanceof Vector2$1) {
       this.velocity.copyFrom(velocity);
     } else {
       this.velocity.set(velocity.x, velocity.y);
     }
     this.wakeUp();
-    const oldDirection = oldVelocity.lengthSquared() > MOVEMENT_EPSILON_SQ ? oldVelocity.clone().normalize() : new Vector2(0, 0);
-    const newDirection = this.velocity.lengthSquared() > MOVEMENT_EPSILON_SQ ? this.velocity.clone().normalize() : new Vector2(0, 0);
+    const oldDirection = oldVelocity.lengthSquared() > MOVEMENT_EPSILON_SQ ? oldVelocity.clone().normalize() : new Vector2$1(0, 0);
+    const newDirection = this.velocity.lengthSquared() > MOVEMENT_EPSILON_SQ ? this.velocity.clone().normalize() : new Vector2$1(0, 0);
     const oldCardinal = this.computeCardinalDirection(oldDirection);
     const newCardinal = this.computeCardinalDirection(newDirection);
     if (oldCardinal !== newCardinal || Math.abs(oldDirection.dot(newDirection) - 1) > 0.01) {
@@ -12454,7 +12543,7 @@ class Entity {
    * @returns This entity for chaining
    */
   freeze() {
-    this.state = EntityState.Static;
+    this.state = EntityState$1.Static;
     this.velocity.set(0, 0);
     this.angularVelocity = 0;
     this.force.set(0, 0);
@@ -12469,7 +12558,7 @@ class Entity {
    */
   unfreeze() {
     if (this.mass > 0) {
-      this.state = EntityState.Dynamic;
+      this.state = EntityState$1.Dynamic;
     }
     return this;
   }
@@ -12480,7 +12569,7 @@ class Entity {
    */
   sleep() {
     if (!this.isStatic()) {
-      this.state |= EntityState.Sleeping;
+      this.state |= EntityState$1.Sleeping;
       this.velocity.set(0, 0);
       this.angularVelocity = 0;
       this.force.set(0, 0);
@@ -12495,7 +12584,7 @@ class Entity {
    * @returns This entity for chaining
    */
   wakeUp() {
-    this.state &= ~EntityState.Sleeping;
+    this.state &= ~EntityState$1.Sleeping;
     this.timeSinceMovement = 0;
     return this;
   }
@@ -12510,7 +12599,7 @@ class Entity {
    * @returns True if static
    */
   isStatic() {
-    return (this.state & EntityState.Static) !== 0 || this.invMass === 0;
+    return (this.state & EntityState$1.Static) !== 0 || this.invMass === 0;
   }
   /**
    * Checks if the entity is dynamic
@@ -12518,7 +12607,7 @@ class Entity {
    * @returns True if dynamic
    */
   isDynamic() {
-    return (this.state & EntityState.Dynamic) !== 0 && this.mass > 0;
+    return (this.state & EntityState$1.Dynamic) !== 0 && this.mass > 0;
   }
   /**
    * Checks if the entity is sleeping
@@ -12526,7 +12615,7 @@ class Entity {
    * @returns True if sleeping
    */
   isSleeping() {
-    return (this.state & EntityState.Sleeping) !== 0;
+    return (this.state & EntityState$1.Sleeping) !== 0;
   }
   /**
    * Checks if the entity is kinematic
@@ -12534,7 +12623,7 @@ class Entity {
    * @returns True if kinematic
    */
   isKinematic() {
-    return (this.state & EntityState.Kinematic) !== 0;
+    return (this.state & EntityState$1.Kinematic) !== 0;
   }
   /**
    * Resets accumulated forces and torques
@@ -12739,7 +12828,7 @@ class Integrator {
    */
   constructor(config) {
     this.config = config;
-    this.gravity = config.gravity?.clone() ?? new Vector2(0, 0);
+    this.gravity = config.gravity?.clone() ?? new Vector2$1(0, 0);
   }
   /**
    * Integrates an entity's motion
@@ -12949,10 +13038,10 @@ class AABBCollider {
     let depth;
     if (overlapX < overlapY) {
       depth = overlapX;
-      normal = aabbA.getCenterX() < aabbB.getCenterX() ? new Vector2(1, 0) : new Vector2(-1, 0);
+      normal = aabbA.getCenterX() < aabbB.getCenterX() ? new Vector2$1(1, 0) : new Vector2$1(-1, 0);
     } else {
       depth = overlapY;
-      normal = aabbA.getCenterY() < aabbB.getCenterY() ? new Vector2(0, 1) : new Vector2(0, -1);
+      normal = aabbA.getCenterY() < aabbB.getCenterY() ? new Vector2$1(0, 1) : new Vector2$1(0, -1);
     }
     const contactPoint = intersection.getCenter();
     return {
@@ -13006,7 +13095,7 @@ class AABBCollider {
     const t = tNear < 0 ? tFar : tNear;
     if (t < 0) return null;
     const point = ray.getPoint(t);
-    let normal = new Vector2(0, 0);
+    let normal = new Vector2$1(0, 0);
     if (Math.abs(point.x - bounds.minX) < 1e-5) normal.set(-1, 0);
     else if (Math.abs(point.x - bounds.maxX) < 1e-5) normal.set(1, 0);
     else if (Math.abs(point.y - bounds.minY) < 1e-5) normal.set(0, -1);
@@ -13088,7 +13177,7 @@ class CircleCollider {
     const depth = minDistance - distance;
     let normal;
     if (distance < 1e-5) {
-      normal = new Vector2(1, 0);
+      normal = new Vector2$1(1, 0);
     } else {
       normal = centerB.sub(centerA).normalize();
     }
@@ -13133,18 +13222,18 @@ class CircleCollider {
       const distToTop = aabb.maxY - circleCenter.y;
       const minDist = Math.min(distToLeft, distToRight, distToBottom, distToTop);
       if (minDist === distToLeft) {
-        normal = new Vector2(-1, 0);
+        normal = new Vector2$1(-1, 0);
       } else if (minDist === distToRight) {
-        normal = new Vector2(1, 0);
+        normal = new Vector2$1(1, 0);
       } else if (minDist === distToBottom) {
-        normal = new Vector2(0, -1);
+        normal = new Vector2$1(0, -1);
       } else {
-        normal = new Vector2(0, 1);
+        normal = new Vector2$1(0, 1);
       }
     } else {
-      normal = new Vector2(closestX - circleCenter.x, closestY - circleCenter.y).normalize();
+      normal = new Vector2$1(closestX - circleCenter.x, closestY - circleCenter.y).normalize();
     }
-    const contactPoint = new Vector2(closestX, closestY);
+    const contactPoint = new Vector2$1(closestX, closestY);
     return {
       entityA: this.entity,
       entityB: other.getEntity(),
@@ -13233,7 +13322,7 @@ class CapsuleCollider {
     const t = tNear < 0 ? tFar : tNear;
     if (t < 0) return null;
     const point = ray.getPoint(t);
-    let normal = new Vector2(0, 0);
+    let normal = new Vector2$1(0, 0);
     if (Math.abs(point.x - bounds.minX) < 1e-5) normal.set(-1, 0);
     else if (Math.abs(point.x - bounds.maxX) < 1e-5) normal.set(1, 0);
     else if (Math.abs(point.y - bounds.minY) < 1e-5) normal.set(0, -1);
@@ -13270,8 +13359,8 @@ class CapsuleCollider {
     const pos = this.entity.position;
     const halfSegment = Math.max(0, height / 2 - radius);
     return {
-      a: new Vector2(pos.x, pos.y - halfSegment),
-      b: new Vector2(pos.x, pos.y + halfSegment)
+      a: new Vector2$1(pos.x, pos.y - halfSegment),
+      b: new Vector2$1(pos.x, pos.y + halfSegment)
     };
   }
   testCircle(circle) {
@@ -13286,7 +13375,7 @@ class CapsuleCollider {
       return null;
     }
     const dist = Math.sqrt(distSq);
-    const normal = dist > 0 ? circleCenter.sub(closest).normalize() : new Vector2(1, 0);
+    const normal = dist > 0 ? circleCenter.sub(closest).normalize() : new Vector2$1(1, 0);
     const depth = minDist - dist;
     return {
       entityA: this.entity,
@@ -13318,7 +13407,7 @@ class CapsuleCollider {
       return null;
     }
     const dist = Math.sqrt(distSq);
-    const normal = dist > 0 ? closestOnBox.sub(closestOnSeg).normalize() : new Vector2(0, 1);
+    const normal = dist > 0 ? closestOnBox.sub(closestOnSeg).normalize() : new Vector2$1(0, 1);
     const depth = capRadius - dist;
     return {
       entityA: this.entity,
@@ -13344,7 +13433,7 @@ class CapsuleCollider {
       return null;
     }
     const dist = Math.sqrt(distSq);
-    const normal = dist > 0 ? p2.sub(p1).normalize() : new Vector2(1, 0);
+    const normal = dist > 0 ? p2.sub(p1).normalize() : new Vector2$1(1, 0);
     const depth = minDist - dist;
     return {
       entityA: this.entity,
@@ -13488,12 +13577,12 @@ class PolygonCollider {
     const b = other.getBounds();
     const halfW = (b.maxX - b.minX) / 2;
     const halfH = (b.maxY - b.minY) / 2;
-    const center = new Vector2((b.minX + b.maxX) / 2, (b.minY + b.maxY) / 2);
+    const center = new Vector2$1((b.minX + b.maxX) / 2, (b.minY + b.maxY) / 2);
     const aabbPolyLocal = [
-      new Vector2(-halfW, -halfH),
-      new Vector2(halfW, -halfH),
-      new Vector2(halfW, halfH),
-      new Vector2(-halfW, halfH)
+      new Vector2$1(-halfW, -halfH),
+      new Vector2$1(halfW, -halfH),
+      new Vector2$1(halfW, halfH),
+      new Vector2$1(-halfW, halfH)
     ];
     const tempEntity = new Entity({ position: center, rotation: 0, mass: 0 });
     entityToPolygonConfig.set(tempEntity, { vertices: aabbPolyLocal, isConvex: true });
@@ -13529,7 +13618,7 @@ class PolygonCollider {
       if (!closestPoint) continue;
       const dist = Math.sqrt(minDistSq);
       if (dist <= r) {
-        const normal = dist > 1e-6 ? center.sub(closestPoint).normalize() : new Vector2(1, 0);
+        const normal = dist > 1e-6 ? center.sub(closestPoint).normalize() : new Vector2$1(1, 0);
         const depth = r - dist;
         const info = {
           entityA: this.entity,
@@ -13637,12 +13726,12 @@ class PolygonCollider {
     const t = ((v1.x - v3.x) * (v3.y - v4.y) - (v1.y - v3.y) * (v3.x - v4.x)) / den;
     const u = -((v1.x - v2.x) * (v1.y - v3.y) - (v1.y - v2.y) * (v1.x - v3.x)) / den;
     if (t >= 0 && t <= ray.length && u >= 0 && u <= 1) {
-      const point = new Vector2(
+      const point = new Vector2$1(
         v1.x + t * (v2.x - v1.x),
         v1.y + t * (v2.y - v1.y)
       );
       const segmentDir = p2.sub(p1).normalize();
-      let normal = new Vector2(-segmentDir.y, segmentDir.x);
+      let normal = new Vector2$1(-segmentDir.y, segmentDir.x);
       if (normal.dot(ray.direction) > 0) {
         normal = normal.mul(-1);
       }
@@ -13667,7 +13756,7 @@ class PolygonCollider {
       for (let i = 0; i < part.length; i++) {
         const v = part[i];
         if (!v) continue;
-        w[i] = new Vector2(v.x * cos - v.y * sin + px, v.x * sin + v.y * cos + py);
+        w[i] = new Vector2$1(v.x * cos - v.y * sin + px, v.x * sin + v.y * cos + py);
       }
       worldParts.push(w);
     }
@@ -13687,7 +13776,7 @@ function gatherSATAxes(a, b) {
     const p1 = p[(i + 1) % p.length];
     if (!p0 || !p1) return;
     const edge = p1.sub(p0);
-    const axis = new Vector2(-edge.y, edge.x).normalize();
+    const axis = new Vector2$1(-edge.y, edge.x).normalize();
     axes.push(axis);
   };
   for (let i = 0; i < a.length; i++) pushAxis(a, i);
@@ -13715,7 +13804,7 @@ function polygonCentroid(poly) {
     cy += v.y;
   }
   const n = poly.length > 0 ? poly.length : 1;
-  return new Vector2(cx / n, cy / n);
+  return new Vector2$1(cx / n, cy / n);
 }
 
 const colliderCache = /* @__PURE__ */ new WeakMap();
@@ -14132,7 +14221,7 @@ class Ray {
 }
 
 function raycast(partition, origin, direction, maxDistance, mask, filter) {
-  const dir = direction.length() > 0 ? direction.normalize() : new Vector2(1, 0);
+  const dir = direction.length() > 0 ? direction.normalize() : new Vector2$1(1, 0);
   const end = origin.add(dir.mul(maxDistance));
   const candidates = partition.raycast(new Ray(origin, dir, maxDistance), mask, filter);
   if (candidates) return candidates;
@@ -14196,8 +14285,8 @@ function raycastAABB(box, origin, dir, maxDistance) {
   if (tmax < tmin || tmin < 0 || tmin > maxDistance) return null;
   const point = origin.add(dir.mul(tmin));
   let normal;
-  if (tmin === tminX) normal = new Vector2(dir.x > 0 ? -1 : 1, 0);
-  else normal = new Vector2(0, dir.y > 0 ? -1 : 1);
+  if (tmin === tminX) normal = new Vector2$1(dir.x > 0 ? -1 : 1, 0);
+  else normal = new Vector2$1(0, dir.y > 0 ? -1 : 1);
   return { entity: box.getEntity(), point, normal, distance: tmin };
 }
 function raycastPolygon(poly, origin, dir, maxDistance) {
@@ -14219,7 +14308,7 @@ function raycastPolygon(poly, origin, dir, maxDistance) {
         bestT = t;
         bestPoint = hit.point;
         const edge = b.sub(a);
-        const n = new Vector2(-edge.y, edge.x).normalize();
+        const n = new Vector2$1(-edge.y, edge.x).normalize();
         bestNormal = n;
       }
     }
@@ -14230,13 +14319,13 @@ function raycastPolygon(poly, origin, dir, maxDistance) {
 function segmentRayIntersection(a, b, r0, r1) {
   const v1 = r0.sub(a);
   const v2 = b.sub(a);
-  const v3 = new Vector2(-(r1.y - r0.y), r1.x - r0.x);
+  const v3 = new Vector2$1(-(r1.y - r0.y), r1.x - r0.x);
   const denom = v2.dot(v3);
   if (Math.abs(denom) < 1e-9) return null;
   const t1 = v2.cross(v1) / denom;
   const t2 = v1.dot(v3) / denom;
   if (t1 >= 0 && t1 <= 1 && t2 >= 0 && t2 <= 1) {
-    const hitPoint = new Vector2(r0.x + (r1.x - r0.x) * t1, r0.y + (r1.y - r0.y) * t1);
+    const hitPoint = new Vector2$1(r0.x + (r1.x - r0.x) * t1, r0.y + (r1.y - r0.y) * t1);
     const dist = hitPoint.sub(r0).length();
     return { point: hitPoint, distance: dist };
   }
@@ -14274,6 +14363,11 @@ class CollisionResolver {
   /**
    * Separates two entities by moving them apart
    * 
+   * This method applies position corrections to resolve penetration between
+   * colliding entities. After applying corrections, it notifies position change
+   * handlers to ensure proper synchronization with game logic (e.g., updating
+   * owner.x/y signals for network sync).
+   * 
    * @param entityA - First entity
    * @param entityB - Second entity
    * @param normal - Separation normal (from A to B)
@@ -14292,9 +14386,11 @@ class CollisionResolver {
     const correctionB = normal.mul(correction * (entityB.invMass / totalInvMass));
     if (!entityA.isStatic()) {
       entityA.position.addInPlace(correctionA);
+      entityA.notifyPositionChange();
     }
     if (!entityB.isStatic()) {
       entityB.position.addInPlace(correctionB);
+      entityB.notifyPositionChange();
     }
   }
   /**
@@ -14413,7 +14509,7 @@ function sweepCircleAABB(circle, box, delta) {
   const p0 = circle.getCenter();
   const dir = delta;
   const maxDist = 1;
-  const origin = new Vector2(0, 0);
+  const origin = new Vector2$1(0, 0);
   const bb = new AABB(expanded.minX - p0.x, expanded.minY - p0.y, expanded.maxX - p0.x, expanded.maxY - p0.y);
   const res = rayVsAABB(origin, dir, bb, maxDist);
   if (!res) return null;
@@ -14436,11 +14532,11 @@ function sweepAABBAABB(a, b, delta) {
   if (tEntry > tExit || tEntry < 0 || tEntry > 1) return null;
   let normal;
   if (Math.min(xEntry, xExit) > Math.min(yEntry, yExit)) {
-    normal = new Vector2(delta.x > 0 ? -1 : 1, 0);
+    normal = new Vector2$1(delta.x > 0 ? -1 : 1, 0);
   } else {
-    normal = new Vector2(0, delta.y > 0 ? -1 : 1);
+    normal = new Vector2$1(0, delta.y > 0 ? -1 : 1);
   }
-  const hitPoint = new Vector2(
+  const hitPoint = new Vector2$1(
     delta.x !== 0 ? delta.x > 0 ? A.maxX : A.minX : (A.minX + A.maxX) * 0.5,
     delta.y !== 0 ? delta.y > 0 ? A.maxY : A.minY : (A.minY + A.maxY) * 0.5
   );
@@ -14462,7 +14558,7 @@ function rayVsAABB(origin, dir, b, maxT) {
   tmin = Math.max(tmin, Math.max(tminX, tminY));
   tmax = Math.min(tmax, Math.min(tmaxX, tmaxY));
   if (tmax < tmin || tmin < 0 || tmin > maxT) return null;
-  const normal = tmin === tminX ? new Vector2(dir.x > 0 ? -1 : 1, 0) : new Vector2(0, dir.y > 0 ? -1 : 1);
+  const normal = tmin === tminX ? new Vector2$1(dir.x > 0 ? -1 : 1, 0) : new Vector2$1(0, dir.y > 0 ? -1 : 1);
   return { t: tmin, normal };
 }
 
@@ -15367,7 +15463,7 @@ class EntityMovementBody {
     this.entity.setVelocity(velocity);
   }
   translate(delta) {
-    this.entity.position.addInPlace(new Vector2(delta.x, delta.y));
+    this.entity.position.addInPlace(new Vector2$1(delta.x, delta.y));
   }
   isStatic() {
     return this.entity.isStatic();
@@ -15624,19 +15720,19 @@ class ZoneManager {
       attachedEntity = config.entity;
       const entityPos = attachedEntity.position;
       const offsetValue = config.offset ?? { x: 0, y: 0 };
-      if (offsetValue instanceof Vector2) {
+      if (offsetValue instanceof Vector2$1) {
         offset = offsetValue.clone();
       } else {
-        offset = new Vector2(offsetValue.x, offsetValue.y);
+        offset = new Vector2$1(offsetValue.x, offsetValue.y);
       }
-      position = new Vector2(entityPos.x + offset.x, entityPos.y + offset.y);
+      position = new Vector2$1(entityPos.x + offset.x, entityPos.y + offset.y);
     } else {
       type = "static";
       const pos = config.position;
-      if (pos instanceof Vector2) {
+      if (pos instanceof Vector2$1) {
         position = pos.clone();
       } else {
-        position = new Vector2(pos.x, pos.y);
+        position = new Vector2$1(pos.x, pos.y);
       }
     }
     const record = {
@@ -15714,10 +15810,10 @@ class ZoneManager {
     }
     if ("offset" in updates && updates.offset !== void 0 && zone.type === "attached") {
       const offsetValue = updates.offset;
-      if (offsetValue instanceof Vector2) {
+      if (offsetValue instanceof Vector2$1) {
         zone.offset = offsetValue.clone();
       } else {
-        zone.offset = new Vector2(offsetValue.x, offsetValue.y);
+        zone.offset = new Vector2$1(offsetValue.x, offsetValue.y);
       }
     }
     return true;
@@ -15821,7 +15917,7 @@ class ZoneManager {
     for (const zone of this.zones.values()) {
       if (zone.type === "attached" && zone.attachedEntity) {
         const entityPos = zone.attachedEntity.position;
-        const offset = zone.offset ?? new Vector2(0, 0);
+        const offset = zone.offset ?? new Vector2$1(0, 0);
         zone.position.set(entityPos.x + offset.x, entityPos.y + offset.y);
       }
       const aabb = new AABB(
@@ -16620,7 +16716,7 @@ class LinearRepulsion {
       throw new Error("LinearRepulsion requires a movement body backed by a physics entity.");
     }
     const targetPosition = this.targetProvider();
-    const toTarget = new Vector2(targetPosition.x - entity.position.x, targetPosition.y - entity.position.y);
+    const toTarget = new Vector2$1(targetPosition.x - entity.position.x, targetPosition.y - entity.position.y);
     const distance = toTarget.length();
     if (distance > 0) {
       toTarget.divInPlace(distance);
@@ -16630,12 +16726,12 @@ class LinearRepulsion {
     const bounds = AABB.fromCenterSize(entity.position.x, entity.position.y, this.repulseRadius * 2, this.repulseRadius * 2);
     const neighbors = this.engine.queryAABB(bounds);
     const ignored = this.ignoredEntity?.();
-    const push = new Vector2(0, 0);
+    const push = new Vector2$1(0, 0);
     for (const other of neighbors) {
       if (other === entity || other === ignored || other.isStatic()) {
         continue;
       }
-      const diff = new Vector2(entity.position.x - other.position.x, entity.position.y - other.position.y);
+      const diff = new Vector2$1(entity.position.x - other.position.x, entity.position.y - other.position.y);
       const d2 = diff.lengthSquared();
       if (d2 > this.repulseRadiusSq || d2 === 0) {
         continue;
@@ -16876,7 +16972,7 @@ class ProjectileMovement {
       return;
     }
     if (this.startPosition === null) {
-      this.startPosition = new Vector2(body.position.x, body.position.y);
+      this.startPosition = new Vector2$1(body.position.x, body.position.y);
     }
     this.elapsed += dt;
     if (this.options.lifetime !== void 0 && this.elapsed >= this.options.lifetime) {
@@ -16895,7 +16991,7 @@ class ProjectileMovement {
         return;
     }
     if (this.startPosition) {
-      this.distanceTraveled = new Vector2(body.position.x, body.position.y).distanceTo(this.startPosition);
+      this.distanceTraveled = new Vector2$1(body.position.x, body.position.y).distanceTo(this.startPosition);
       if (this.options.maxRange !== void 0 && this.distanceTraveled >= this.options.maxRange) {
         this.finish(body);
       }
@@ -17008,7 +17104,7 @@ class SeekAvoid {
       body.setVelocity({ x: 0, y: 0 });
       return;
     }
-    const toTarget = new Vector2(target.position.x - entity.position.x, target.position.y - entity.position.y);
+    const toTarget = new Vector2$1(target.position.x - entity.position.x, target.position.y - entity.position.y);
     const distSq = toTarget.lengthSquared();
     let arrived = false;
     if (distSq <= this.arriveRadiusSq) {
@@ -17019,13 +17115,13 @@ class SeekAvoid {
     }
     const bounds = AABB.fromCenterSize(entity.position.x, entity.position.y, this.repulseRadius * 2, this.repulseRadius * 2);
     const neighbors = this.engine.queryAABB(bounds);
-    const push = new Vector2(0, 0);
+    const push = new Vector2$1(0, 0);
     if (!arrived) {
       for (const other of neighbors) {
         if (other === entity || other === target || other.isStatic()) {
           continue;
         }
-        const diff = new Vector2(entity.position.x - other.position.x, entity.position.y - other.position.y);
+        const diff = new Vector2$1(entity.position.x - other.position.x, entity.position.y - other.position.y);
         let d2 = diff.lengthSquared();
         if (d2 > this.repulseRadiusSq) {
           continue;
@@ -17109,7 +17205,7 @@ class RpgCommonMap {
     this.data = signal(null);
     this.physic = new PhysicsEngine({
       timeStep: 1 / 60,
-      gravity: new Vector2(0, 0),
+      gravity: new Vector2$1(0, 0),
       enableSleep: false
     });
     this.moveManager = new MovementManager(() => this.physic);
@@ -17123,12 +17219,33 @@ class RpgCommonMap {
      * It's shared using the share() operator, meaning that all subscribers will receive
      * events from a single interval rather than creating multiple intervals.
      * 
+     * ## Physics Loop Architecture
+     * 
+     * The physics simulation is centralized in this game loop:
+     * 
+     * 1. **Input Processing** (`processInput`): Only updates entity velocities, does NOT step physics
+     * 2. **Game Loop** (`tick$` -> `runFixedTicks`): Executes physics simulation with fixed timestep
+     * 3. **Fixed Timestep Pattern**: Accumulator-based approach ensures deterministic physics
+     * 
+     * ```
+     * Input Events ─────────────────────────────────────────────────────────────►
+     *     │                                                                       
+     *     ▼ (update velocity only)                                               
+     * ┌─────────────────────────────────────────────────────────────────────────┐
+     * │                        Game Loop (tick$)                                │
+     * │  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐       │
+     * │  │ updateMovements │ → │  stepOneTick    │ → │ postTickUpdates │       │
+     * │  │ (apply velocity)│   │ (physics step)  │   │ (zones, sync)   │       │
+     * │  └─────────────────┘   └─────────────────┘   └─────────────────┘       │
+     * └─────────────────────────────────────────────────────────────────────────┘
+     * ```
+     * 
      * @example
      * ```ts
-     * // Subscribe to the game tick to update entity positions
-     * map.tick$.subscribe(timestamp => {
-     *   // Update game entities based on elapsed time
-     *   this.updateEntities(timestamp);
+     * // Subscribe to the game tick for custom updates
+     * map.tick$.subscribe(({ delta, timestamp }) => {
+     *   // Custom game logic runs alongside physics
+     *   this.updateCustomEntities(delta);
      * });
      * ```
      */
@@ -17304,6 +17421,43 @@ class RpgCommonMap {
   getObjectById(id) {
     return this.players()[id] ?? this.events()[id];
   }
+  /**
+   * Execute physics simulation with fixed timestep
+   * 
+   * This method runs the physics engine using a fixed timestep accumulator pattern.
+   * It ensures deterministic physics regardless of frame rate by:
+   * 1. Accumulating delta time
+   * 2. Running fixed-size physics steps until the accumulator is depleted
+   * 3. Calling `updateMovements()` before each step to apply velocity changes
+   * 4. Running post-tick updates (zones, callbacks) after each step
+   * 
+   * ## Architecture
+   * 
+   * The physics loop is centralized here and called from `tick$` subscription.
+   * Input processing (`processInput`) only updates entity velocities - it does NOT
+   * step the physics. This ensures:
+   * - Consistent physics timing (60fps fixed timestep)
+   * - No double-stepping when inputs are processed
+   * - Proper accumulator-based interpolation support
+   * 
+   * @param deltaMs - Time elapsed since last call in milliseconds
+   * @param hooks - Optional callbacks for before/after each physics step
+   * @returns Number of physics ticks executed
+   * 
+   * @example
+   * ```ts
+   * // Called automatically by tick$ subscription
+   * this.tickSubscription = this.tick$.subscribe(({ delta }) => {
+   *   this.runFixedTicks(delta);
+   * });
+   * 
+   * // Or manually with hooks for debugging
+   * this.runFixedTicks(16, {
+   *   beforeStep: () => console.log('Before physics step'),
+   *   afterStep: (tick) => console.log(`Physics tick ${tick} completed`)
+   * });
+   * ```
+   */
   runFixedTicks(deltaMs, hooks) {
     if (!Number.isFinite(deltaMs) || deltaMs <= 0) {
       return 0;
@@ -17314,12 +17468,46 @@ class RpgCommonMap {
     while (this.physicsAccumulatorMs >= fixedStepMs) {
       this.physicsAccumulatorMs -= fixedStepMs;
       hooks?.beforeStep?.();
+      this.physic.updateMovements();
       const tick = this.physic.stepOneTick();
       executed += 1;
+      this.runPostTickUpdates();
       hooks?.afterStep?.(tick);
     }
     return executed;
   }
+  /**
+   * Force a single physics tick outside of the normal game loop
+   * 
+   * This method is primarily used for **client-side prediction** where the client
+   * needs to immediately simulate physics in response to local input, rather than
+   * waiting for the next game loop tick.
+   * 
+   * ## Use Cases
+   * 
+   * - **Client-side prediction**: Immediately simulate player movement for responsive feel
+   * - **Testing**: Force a physics step in unit tests
+   * - **Special effects**: Immediate physics response for specific game events
+   * 
+   * ## Important
+   * 
+   * This method should NOT be used on the server for normal input processing.
+   * Server-side physics is handled by `runFixedTicks` in the main game loop to ensure
+   * deterministic simulation.
+   * 
+   * @param hooks - Optional callbacks for before/after the physics step
+   * @returns The physics tick number
+   * 
+   * @example
+   * ```ts
+   * // Client-side: immediately simulate predicted movement
+   * class RpgClientMap extends RpgCommonMap {
+   *   stepPredictionTick(): void {
+   *     this.forceSingleTick();
+   *   }
+   * }
+   * ```
+   */
   forceSingleTick(hooks) {
     hooks?.beforeStep?.();
     this.physic.updateMovements();
@@ -17613,13 +17801,13 @@ class RpgCommonMap {
         width: boxWidth,
         height: boxHeight,
         mass: Infinity,
-        state: EntityState.Static,
+        state: EntityState$1.Static,
         restitution: 0
       });
       entity.freeze();
       const localVertices = points.map((point) => {
         const [px, py] = point;
-        return new Vector2(px - centerX, py - centerY);
+        return new Vector2$1(px - centerX, py - centerY);
       });
       assignPolygonCollider(entity, { vertices: localVertices });
     } else {
@@ -17636,7 +17824,7 @@ class RpgCommonMap {
         width: boxWidth,
         height: boxHeight,
         mass: Infinity,
-        state: EntityState.Static,
+        state: EntityState$1.Static,
         restitution: 0
       });
       entity.freeze();
@@ -17647,23 +17835,60 @@ class RpgCommonMap {
    * Add a character to the physics world
    * @private
    */
+  /**
+   * Add a character entity to the physics world
+   * 
+   * Creates a physics entity for a character (player or NPC) with proper position handling.
+   * The owner's x/y signals represent **top-left** coordinates, while the physics entity
+   * uses **center** coordinates internally.
+   * 
+   * ## Position System
+   * 
+   * - `owner.x()` / `owner.y()` → **top-left** corner of the character's hitbox
+   * - `entity.position` → **center** of the physics collider
+   * - Conversion: `center = topLeft + (size / 2)`
+   * 
+   * @param options - Character configuration
+   * @returns The character's unique ID
+   * 
+   * @example
+   * ```ts
+   * // Player at top-left position (100, 100) with 32x32 hitbox
+   * // Physics entity will be at center (116, 116)
+   * this.addCharacter({
+   *   owner: player,
+   *   x: 116,  // center X (ignored, uses owner.x())
+   *   y: 116,  // center Y (ignored, uses owner.y())
+   *   kind: "hero"
+   * });
+   * ```
+   * 
+   * @private
+   */
   addCharacter(options) {
     if (!options || typeof options.owner?.id !== "string") {
       throw new Error("Character requires an owner object with a string id");
     }
     const owner = options.owner;
     const id = owner.id;
-    const radius = owner.hitbox?.w ?? options.radius ?? 25;
-    const diameter = radius * 2;
-    const topLeftX = owner.x() - radius;
-    const topLeftY = owner.y() - radius;
-    const centerX = topLeftX + diameter / 2;
-    const centerY = topLeftY + diameter / 2;
+    const hitbox = typeof owner.hitbox === "function" ? owner.hitbox() : owner.hitbox;
+    const width = hitbox?.w ?? 32;
+    const height = hitbox?.h ?? 32;
+    const radius = Math.max(width, height) / 2;
+    const topLeftX = owner.x();
+    const topLeftY = owner.y();
+    const centerX = topLeftX + width / 2;
+    const centerY = topLeftY + height / 2;
     const isStatic = !!options.isStatic;
     const entity = this.physic.createEntity({
       uuid: id,
       position: { x: centerX, y: centerY },
+      // Use radius for circular collision detection
       radius: Math.max(radius, 1),
+      // Also store explicit width/height for consistent position conversions
+      // This ensures getBodyPosition/setBodyPosition use the same dimensions
+      width,
+      height,
       mass: options.mass ?? (isStatic ? Infinity : 1),
       friction: options.friction ?? 0.4,
       linearDamping: isStatic ? 1 : 0.2,
@@ -17691,17 +17916,21 @@ class RpgCommonMap {
         owner.animationName.set("stand");
       }
     });
+    const entityWidth = width;
+    const entityHeight = height;
     entity.onPositionChange(({ x, y }) => {
-      const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
-      const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
-      const topLeftX2 = x - width / 2;
-      const topLeftY2 = y - height / 2;
+      const topLeftX2 = x - entityWidth / 2;
+      const topLeftY2 = y - entityHeight / 2;
+      let changed = false;
       if (typeof owner.x === "function" && typeof owner.x.set === "function") {
         owner.x.set(Math.round(topLeftX2));
-        owner.applyFrames?.();
+        changed = true;
       }
       if (typeof owner.y === "function" && typeof owner.y.set === "function") {
         owner.y.set(Math.round(topLeftY2));
+        changed = true;
+      }
+      if (changed) {
         owner.applyFrames?.();
       }
     });
@@ -17917,11 +18146,11 @@ class RpgCommonMap {
   setBodyPosition(id, x, y, mode = "center") {
     const entity = this.physic.getEntityByUUID(id);
     if (!entity) return;
+    const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
+    const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
     let centerX = x;
     let centerY = y;
     if (mode === "top-left") {
-      const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
-      const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
       centerX = x + width / 2;
       centerY = y + height / 2;
     }
@@ -18387,113 +18616,664 @@ var PrebuiltGui = /* @__PURE__ */ ((PrebuiltGui2) => {
   return PrebuiltGui2;
 })(PrebuiltGui || {});
 
-function WithComponentManager(Base) {
-  return class extends Base {
-    setGraphic(graphic) {
-      if (Array.isArray(graphic)) {
-        this.graphics.set(graphic);
-      } else {
-        this.graphics.set([graphic]);
-      }
-    }
-  };
-}
-
-var __defProp$3 = Object.defineProperty;
-var __name = (target, value) => __defProp$3(target, "name", { value, configurable: true });
-
-// src/inject.ts
-function provide(context, name, value) {
-  context.set("inject:" + name, value);
-  return value;
-}
-__name(provide, "provide");
-function isInjected(context, name) {
-  return context.get("injected:" + name) === true;
-}
-__name(isInjected, "isInjected");
-function isProvided(context, name) {
-  return context.get("inject:" + name) !== void 0;
-}
-__name(isProvided, "isProvided");
-function inject$1(context, service, args = []) {
-  const isClass = typeof service === "function";
-  const name = isClass ? service.name : service;
-  const value = context.get("inject:" + name);
-  if (value) {
-    context.set("injected:" + name, true);
-    return value;
+const _Vector2 = class _Vector2 {
+  /**
+   * Creates a new Vector2
+   * 
+   * @param x - X component (default: 0)
+   * @param y - Y component (default: 0)
+   */
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
   }
-  throw new Error(`Injection provider ${name} not found`);
-}
-__name(inject$1, "inject");
-function override(providers, newProvider, options) {
-  let { upsert = false, key } = options ?? {};
-  if (!key) {
-    key = typeof newProvider === "function" ? newProvider.name : newProvider.provide;
+  /**
+   * Creates a copy of this vector
+   * 
+   * @returns A new Vector2 with the same values
+   */
+  clone() {
+    return new _Vector2(this.x, this.y);
   }
-  const flatProviders = providers.flat();
-  const exists = flatProviders.some((provider) => {
-    if (typeof provider === "function") {
-      return provider.name === key;
-    } else if (typeof provider === "object") {
-      return provider.provide === key;
-    }
-    return false;
-  });
-  const mappedProviders = flatProviders.map((provider) => {
-    if (typeof provider === "function" && provider.name === key) {
-      return newProvider;
-    } else if (typeof provider === "object" && provider.provide === key) {
-      return newProvider;
-    }
-    return provider;
-  });
-  if (upsert && !exists) {
-    mappedProviders.push(newProvider);
+  /**
+   * Sets the components of this vector
+   * 
+   * @param x - X component
+   * @param y - Y component
+   * @returns This vector for chaining
+   */
+  set(x, y) {
+    this.x = x;
+    this.y = y;
+    return this;
   }
-  return mappedProviders;
-}
-__name(override, "override");
-function findProviders(providers, name) {
-  const results = [];
-  for (const provider of providers) {
-    if (Array.isArray(provider)) {
-      results.push(...findProviders(provider, name));
-    } else if (findProvider(provider, name)) {
-      results.push(provider);
-    }
+  /**
+   * Copies values from another vector
+   * 
+   * @param other - Vector to copy from
+   * @returns This vector for chaining
+   */
+  copyFrom(other) {
+    this.x = other.x;
+    this.y = other.y;
+    return this;
   }
-  return results;
-}
-__name(findProviders, "findProviders");
-function findProvider(providers, name) {
-  if (!Array.isArray(providers)) {
-    if (typeof providers === "object" && "provide" in providers) {
-      const provider = providers;
-      const providerName = typeof provider.provide === "function" ? provider.provide.name : provider.provide;
-      if (name instanceof RegExp) {
-        if (name.test(providerName)) return providers;
-      } else {
-        if (providerName === name) return providers;
-      }
-    }
-    return null;
+  /**
+   * Adds another vector to this vector (immutable)
+   * 
+   * @param other - Vector to add
+   * @returns New vector with the result
+   */
+  add(other) {
+    return new _Vector2(this.x + other.x, this.y + other.y);
   }
-  for (const provider of providers) {
-    if (Array.isArray(provider)) {
-      const found = findProvider(provider, name);
-      if (found) return found;
-      continue;
-    }
-    if (typeof provider === "object" && "provide" in provider) {
-      const providerName = typeof provider.provide === "function" ? provider.provide.name : provider.provide;
-      if (name instanceof RegExp) {
-        if (name.test(providerName)) return provider;
-      } else {
-        if (providerName === name) return provider;
-      }
-    }
+  /**
+   * Adds another vector to this vector (in-place)
+   * 
+   * @param other - Vector to add
+   * @returns This vector for chaining
+   */
+  addInPlace(other) {
+    this.x += other.x;
+    this.y += other.y;
+    return this;
+  }
+  /**
+   * Subtracts another vector from this vector (immutable)
+   * 
+   * @param other - Vector to subtract
+   * @returns New vector with the result
+   */
+  sub(other) {
+    return new _Vector2(this.x - other.x, this.y - other.y);
+  }
+  /**
+   * Subtracts another vector from this vector (in-place)
+   * 
+   * @param other - Vector to subtract
+   * @returns This vector for chaining
+   */
+  subInPlace(other) {
+    this.x -= other.x;
+    this.y -= other.y;
+    return this;
+  }
+  /**
+   * Multiplies this vector by a scalar (immutable)
+   * 
+   * @param scalar - Scalar value
+   * @returns New vector with the result
+   */
+  mul(scalar) {
+    return new _Vector2(this.x * scalar, this.y * scalar);
+  }
+  /**
+   * Multiplies this vector by a scalar (in-place)
+   * 
+   * @param scalar - Scalar value
+   * @returns This vector for chaining
+   */
+  mulInPlace(scalar) {
+    this.x *= scalar;
+    this.y *= scalar;
+    return this;
+  }
+  /**
+   * Divides this vector by a scalar (immutable)
+   * 
+   * @param scalar - Scalar value (must not be zero)
+   * @returns New vector with the result
+   */
+  div(scalar) {
+    return new _Vector2(this.x / scalar, this.y / scalar);
+  }
+  /**
+   * Divides this vector by a scalar (in-place)
+   * 
+   * @param scalar - Scalar value (must not be zero)
+   * @returns This vector for chaining
+   */
+  divInPlace(scalar) {
+    this.x /= scalar;
+    this.y /= scalar;
+    return this;
+  }
+  /**
+   * Calculates the dot product with another vector
+   * 
+   * @param other - Vector to dot with
+   * @returns Dot product value
+   */
+  dot(other) {
+    return this.x * other.x + this.y * other.y;
+  }
+  /**
+   * Calculates the 2D cross product (scalar result)
+   * 
+   * @param other - Vector to cross with
+   * @returns Cross product value (z-component of 3D cross product)
+   */
+  cross(other) {
+    return this.x * other.y - this.y * other.x;
+  }
+  /**
+   * Calculates the squared length (faster than length, avoids sqrt)
+   * 
+   * @returns Squared length
+   */
+  lengthSquared() {
+    return this.x * this.x + this.y * this.y;
+  }
+  /**
+   * Calculates the length (magnitude) of the vector
+   * 
+   * @returns Length
+   */
+  length() {
+    return Math.sqrt(this.lengthSquared());
+  }
+  /**
+   * Normalizes this vector to unit length (immutable)
+   * 
+   * @returns New normalized vector
+   */
+  normalize() {
+    const len = this.length();
+    if (len === 0) {
+      return new _Vector2(0, 0);
+    }
+    return this.div(len);
+  }
+  /**
+   * Normalizes this vector to unit length (in-place)
+   * 
+   * @returns This vector for chaining
+   */
+  normalizeInPlace() {
+    const len = this.length();
+    if (len === 0) {
+      this.x = 0;
+      this.y = 0;
+    } else {
+      this.divInPlace(len);
+    }
+    return this;
+  }
+  /**
+   * Calculates the distance to another vector
+   * 
+   * @param other - Target vector
+   * @returns Distance
+   */
+  distanceTo(other) {
+    return this.sub(other).length();
+  }
+  /**
+   * Calculates the squared distance to another vector (faster)
+   * 
+   * @param other - Target vector
+   * @returns Squared distance
+   */
+  distanceToSquared(other) {
+    return this.sub(other).lengthSquared();
+  }
+  /**
+   * Rotates this vector by an angle in radians (immutable)
+   * 
+   * @param angle - Angle in radians
+   * @returns New rotated vector
+   */
+  rotate(angle) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return new _Vector2(
+      this.x * cos - this.y * sin,
+      this.x * sin + this.y * cos
+    );
+  }
+  /**
+   * Rotates this vector by an angle in radians (in-place)
+   * 
+   * @param angle - Angle in radians
+   * @returns This vector for chaining
+   */
+  rotateInPlace(angle) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const x = this.x * cos - this.y * sin;
+    const y = this.x * sin + this.y * cos;
+    this.x = x;
+    this.y = y;
+    return this;
+  }
+  /**
+   * Calculates the angle of this vector in radians
+   * 
+   * @returns Angle in radians (range: -π to π)
+   */
+  angle() {
+    return Math.atan2(this.y, this.x);
+  }
+  /**
+   * Linearly interpolates between this vector and another
+   * 
+   * @param other - Target vector
+   * @param t - Interpolation factor (0 to 1)
+   * @returns New interpolated vector
+   */
+  lerp(other, t) {
+    return new _Vector2(
+      this.x + (other.x - this.x) * t,
+      this.y + (other.y - this.y) * t
+    );
+  }
+  /**
+   * Checks if this vector equals another (with epsilon tolerance)
+   * 
+   * @param other - Vector to compare
+   * @param epsilon - Tolerance for comparison (default: 1e-5)
+   * @returns True if vectors are approximately equal
+   */
+  equals(other, epsilon = 1e-5) {
+    return Math.abs(this.x - other.x) < epsilon && Math.abs(this.y - other.y) < epsilon;
+  }
+  /**
+   * Returns a string representation of this vector
+   * 
+   * @returns String representation
+   */
+  toString() {
+    return `Vector2(${this.x}, ${this.y})`;
+  }
+};
+_Vector2.ZERO = new _Vector2(0, 0);
+_Vector2.UNIT_X = new _Vector2(1, 0);
+_Vector2.UNIT_Y = new _Vector2(0, 1);
+let Vector2 = _Vector2;
+
+var EntityState = /* @__PURE__ */ ((EntityState2) => {
+  EntityState2[EntityState2["Static"] = 1] = "Static";
+  EntityState2[EntityState2["Dynamic"] = 2] = "Dynamic";
+  EntityState2[EntityState2["Sleeping"] = 4] = "Sleeping";
+  EntityState2[EntityState2["Kinematic"] = 8] = "Kinematic";
+  return EntityState2;
+})(EntityState || {});
+
+function WithComponentManager(Base) {
+  return class extends Base {
+    setGraphic(graphic) {
+      if (Array.isArray(graphic)) {
+        this.graphics.set(graphic);
+      } else {
+        this.graphics.set([graphic]);
+      }
+    }
+    /**
+     * Set components to display above the player graphic
+     * 
+     * Components are displayed above the player's sprite and can include
+     * text, bars, shapes, or any combination. The components are synchronized
+     * to all clients on the map.
+     * 
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * // Single text component
+     * player.setComponentsTop(Components.text('{name}'));
+     * 
+     * // Multiple components vertically
+     * player.setComponentsTop([
+     *   Components.text('HP: {hp}'),
+     *   Components.text('{name}')
+     * ]);
+     * 
+     * // Table layout (columns)
+     * player.setComponentsTop([
+     *   [Components.text('{hp}'), Components.text('{name}')]
+     * ]);
+     * 
+     * // With layout options
+     * player.setComponentsTop([
+     *   Components.text('HP: {hp}'),
+     *   Components.text('{name}')
+     * ], {
+     *   width: 100,
+     *   height: 30,
+     *   marginBottom: -10
+     * });
+     * ```
+     */
+    setComponentsTop(layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      const data = {
+        components: normalized,
+        layout: options || {}
+      };
+      this.componentsTop.set(JSON.stringify(data));
+    }
+    /**
+     * Set components to display below the player graphic
+     * 
+     * Components are displayed below the player's sprite and can include
+     * text, bars, shapes, or any combination. The components are synchronized
+     * to all clients on the map.
+     * 
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * player.setComponentsBottom(Components.shape({
+     *   fill: '#ff0000',
+     *   type: 'rectangle',
+     *   width: 32,
+     *   height: 32
+     * }), {
+     *   marginBottom: 16
+     * });
+     * ```
+     */
+    setComponentsBottom(layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      const data = {
+        components: normalized,
+        layout: options || {}
+      };
+      this.componentsBottom.set(JSON.stringify(data));
+    }
+    /**
+     * Set components to display at the center of the player graphic
+     * 
+     * Components are displayed at the center of the player's sprite.
+     * Be careful: if you assign, it deletes the graphics and if the lines are superimposed.
+     * 
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * player.setComponentsCenter([
+     *   Components.text('{name}'),
+     *   Components.hpBar()
+     * ]);
+     * ```
+     */
+    setComponentsCenter(layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      const data = {
+        components: normalized,
+        layout: options || {}
+      };
+      this.componentsCenter.set(JSON.stringify(data));
+    }
+    /**
+     * Set components to display to the left of the player graphic
+     * 
+     * Components are displayed to the left of the player's sprite.
+     * 
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * player.setComponentsLeft([
+     *   Components.text('{name}'),
+     *   Components.hpBar()
+     * ]);
+     * ```
+     */
+    setComponentsLeft(layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      const data = {
+        components: normalized,
+        layout: options || {}
+      };
+      this.componentsLeft.set(JSON.stringify(data));
+    }
+    /**
+     * Set components to display to the right of the player graphic
+     * 
+     * Components are displayed to the right of the player's sprite.
+     * 
+     * @param layout - Component(s) to display, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * player.setComponentsRight([
+     *   Components.text('{name}'),
+     *   Components.hpBar()
+     * ]);
+     * ```
+     */
+    setComponentsRight(layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      const data = {
+        components: normalized,
+        layout: options || {}
+      };
+      this.componentsRight.set(JSON.stringify(data));
+    }
+    /**
+     * Remove components from a specific position
+     * 
+     * Deletes all components at the specified position.
+     * 
+     * @param position - Position of the components: 'top', 'center', 'bottom', 'left', or 'right'
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * player.removeComponents('top');
+     * ```
+     */
+    removeComponents(position) {
+      switch (position) {
+        case "top":
+          this.componentsTop.set(null);
+          break;
+        case "center":
+          this.componentsCenter.set(null);
+          break;
+        case "bottom":
+          this.componentsBottom.set(null);
+          break;
+        case "left":
+          this.componentsLeft.set(null);
+          break;
+        case "right":
+          this.componentsRight.set(null);
+          break;
+      }
+    }
+    /**
+     * Merge components with existing components at a specific position
+     * 
+     * Merges new components with existing components at the specified position.
+     * 
+     * @param position - Position of the components: 'top', 'center', 'bottom', 'left', or 'right'
+     * @param layout - Component(s) to merge, can be single, array, or 2D array
+     * @param options - Optional layout options for positioning and sizing
+     * @returns void
+     * 
+     * @example
+     * ```ts
+     * // First set some components
+     * player.setComponentsTop([Components.text('{name}')]);
+     * 
+     * // Then merge additional components
+     * player.mergeComponents('top', [Components.hpBar()], {
+     *   width: 100
+     * });
+     * ```
+     */
+    mergeComponents(position, layout, options) {
+      const normalized = this.normalizeComponents(layout);
+      let existingData = null;
+      let signal = null;
+      switch (position) {
+        case "top":
+          signal = this.componentsTop;
+          break;
+        case "center":
+          signal = this.componentsCenter;
+          break;
+        case "bottom":
+          signal = this.componentsBottom;
+          break;
+        case "left":
+          signal = this.componentsLeft;
+          break;
+        case "right":
+          signal = this.componentsRight;
+          break;
+      }
+      const existingJson = signal();
+      if (existingJson) {
+        try {
+          existingData = JSON.parse(existingJson);
+        } catch (e) {
+          existingData = null;
+        }
+      }
+      const existingComponents = existingData?.components || [];
+      const mergedComponents = [...existingComponents, ...normalized];
+      const mergedLayout = {
+        ...existingData?.layout || {},
+        ...options || {}
+      };
+      const data = {
+        components: mergedComponents,
+        layout: mergedLayout
+      };
+      signal.set(JSON.stringify(data));
+    }
+    /**
+     * Normalize component input to a consistent structure
+     * 
+     * Converts various input formats (single component, array, 2D array)
+     * into a normalized 2D array structure for consistent rendering.
+     * 
+     * @param components - Component input in any format
+     * @returns Normalized 2D array of components
+     */
+    normalizeComponents(components) {
+      if (!components) {
+        return [];
+      }
+      if (!Array.isArray(components)) {
+        return [[components]];
+      }
+      if (components.length > 0 && Array.isArray(components[0])) {
+        return components;
+      }
+      return components.map((comp) => [comp]);
+    }
+  };
+}
+
+var __defProp$3 = Object.defineProperty;
+var __name = (target, value) => __defProp$3(target, "name", { value, configurable: true });
+
+// src/inject.ts
+function provide(context, name, value) {
+  context.set("inject:" + name, value);
+  return value;
+}
+__name(provide, "provide");
+function isInjected(context, name) {
+  return context.get("injected:" + name) === true;
+}
+__name(isInjected, "isInjected");
+function isProvided(context, name) {
+  return context.get("inject:" + name) !== void 0;
+}
+__name(isProvided, "isProvided");
+function inject$1(context, service, args = []) {
+  const isClass = typeof service === "function";
+  const name = isClass ? service.name : service;
+  const value = context.get("inject:" + name);
+  if (value) {
+    context.set("injected:" + name, true);
+    return value;
+  }
+  throw new Error(`Injection provider ${name} not found`);
+}
+__name(inject$1, "inject");
+function override(providers, newProvider, options) {
+  let { upsert = false, key } = options ?? {};
+  if (!key) {
+    key = typeof newProvider === "function" ? newProvider.name : newProvider.provide;
+  }
+  const flatProviders = providers.flat();
+  const exists = flatProviders.some((provider) => {
+    if (typeof provider === "function") {
+      return provider.name === key;
+    } else if (typeof provider === "object") {
+      return provider.provide === key;
+    }
+    return false;
+  });
+  const mappedProviders = flatProviders.map((provider) => {
+    if (typeof provider === "function" && provider.name === key) {
+      return newProvider;
+    } else if (typeof provider === "object" && provider.provide === key) {
+      return newProvider;
+    }
+    return provider;
+  });
+  if (upsert && !exists) {
+    mappedProviders.push(newProvider);
+  }
+  return mappedProviders;
+}
+__name(override, "override");
+function findProviders(providers, name) {
+  const results = [];
+  for (const provider of providers) {
+    if (Array.isArray(provider)) {
+      results.push(...findProviders(provider, name));
+    } else if (findProvider(provider, name)) {
+      results.push(provider);
+    }
+  }
+  return results;
+}
+__name(findProviders, "findProviders");
+function findProvider(providers, name) {
+  if (!Array.isArray(providers)) {
+    if (typeof providers === "object" && "provide" in providers) {
+      const provider = providers;
+      const providerName = typeof provider.provide === "function" ? provider.provide.name : provider.provide;
+      if (name instanceof RegExp) {
+        if (name.test(providerName)) return providers;
+      } else {
+        if (providerName === name) return providers;
+      }
+    }
+    return null;
+  }
+  for (const provider of providers) {
+    if (Array.isArray(provider)) {
+      const found = findProvider(provider, name);
+      if (found) return found;
+      continue;
+    }
+    if (typeof provider === "object" && "provide" in provider) {
+      const providerName = typeof provider.provide === "function" ? provider.provide.name : provider.provide;
+      if (name instanceof RegExp) {
+        if (name.test(providerName)) return provider;
+      } else {
+        if (providerName === name) return provider;
+      }
+    }
   }
   return null;
 }
@@ -19173,7 +19953,7 @@ function WithMoveManager(Base) {
       staticTarget.freeze();
       map.moveManager.add(
         this.id,
-        new SeekAvoid(engine, () => staticTarget, 3, 50, 5)
+        new SeekAvoid(engine, () => staticTarget, 80, 140, 80, 48)
       );
     }
     /**
@@ -22312,6 +23092,10 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     this.conn = null;
     this.touchSide = false;
     // Protection against map change loops
+    /** Internal: Shapes attached to this player */
+    this._attachedShapes = /* @__PURE__ */ new Map();
+    /** Internal: Shapes where this player is currently located */
+    this._inShapes = /* @__PURE__ */ new Set();
     /** Last processed client input timestamp for reconciliation */
     this.lastProcessedInputTs = 0;
     /** Last processed client input frame for reconciliation with server tick */
@@ -22331,12 +23115,29 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     this.addParameter(DEX, DEX_CURVE);
     this.addParameter(AGI, AGI_CURVE);
     this.allRecovery();
+    let lastEmitted = null;
+    let pendingUpdate = null;
+    let updateScheduled = false;
     combineLatest$1([this.x.observable, this.y.observable]).subscribe(([x, y]) => {
-      this.frames = [...this.frames, {
-        x,
-        y,
-        ts: Date.now()
-      }];
+      pendingUpdate = { x, y };
+      if (!updateScheduled) {
+        updateScheduled = true;
+        queueMicrotask(() => {
+          if (pendingUpdate) {
+            const { x: x2, y: y2 } = pendingUpdate;
+            if (!lastEmitted || lastEmitted.x !== x2 || lastEmitted.y !== y2) {
+              this.frames = [...this.frames, {
+                x: x2,
+                y: y2,
+                ts: Date.now()
+              }];
+              lastEmitted = { x: x2, y: y2 };
+            }
+            pendingUpdate = null;
+          }
+          updateScheduled = false;
+        });
+      }
     });
   }
   _onInit() {
@@ -22411,22 +23212,22 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
    * ```
    */
   async autoChangeMap(nextPosition, forcedDirection) {
-    const map = this.getCurrentMap();
-    if (!map) return false;
-    const worldMaps = map.getWorldMapsManager?.();
+    const map2 = this.getCurrentMap();
+    if (!map2) return false;
+    const worldMaps = map2.getWorldMapsManager?.();
     let ret = false;
-    if (worldMaps && map) {
+    if (worldMaps && map2) {
       const direction = forcedDirection ?? this.getDirection();
-      const marginLeftRight = (map.tileWidth ?? 32) / 2;
-      const marginTopDown = (map.tileHeight ?? 32) / 2;
-      const worldPositionX = (map.worldX ?? 0) + this.x();
-      const worldPositionY = (map.worldY ?? 0) + this.y();
+      const marginLeftRight = (map2.tileWidth ?? 32) / 2;
+      const marginTopDown = (map2.tileHeight ?? 32) / 2;
+      const worldPositionX = (map2.worldX ?? 0) + this.x();
+      const worldPositionY = (map2.worldY ?? 0) + this.y();
       const changeMap = async (adjacentCoords, positionCalculator) => {
         if (this.touchSide) {
           return false;
         }
         this.touchSide = true;
-        const [nextMap] = worldMaps.getAdjacentMaps(map, adjacentCoords);
+        const [nextMap] = worldMaps.getAdjacentMaps(map2, adjacentCoords);
         if (!nextMap) {
           this.touchSide = false;
           return false;
@@ -22446,34 +23247,34 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
       };
       if (nextPosition.x < marginLeftRight && direction === Direction.Left) {
         ret = await changeMap({
-          x: (map.worldX ?? 0) - 1,
+          x: (map2.worldX ?? 0) - 1,
           y: worldPositionY
         }, (nextMapInfo) => ({
           x: nextMapInfo.width - this.hitbox().w - marginLeftRight,
-          y: (map.worldY ?? 0) - (nextMapInfo.y ?? 0) + nextPosition.y
+          y: (map2.worldY ?? 0) - (nextMapInfo.y ?? 0) + nextPosition.y
         }));
-      } else if (nextPosition.x > map.widthPx - this.hitbox().w - marginLeftRight && direction === Direction.Right) {
+      } else if (nextPosition.x > map2.widthPx - this.hitbox().w - marginLeftRight && direction === Direction.Right) {
         ret = await changeMap({
-          x: (map.worldX ?? 0) + map.widthPx + 1,
+          x: (map2.worldX ?? 0) + map2.widthPx + 1,
           y: worldPositionY
         }, (nextMapInfo) => ({
           x: marginLeftRight,
-          y: (map.worldY ?? 0) - (nextMapInfo.y ?? 0) + nextPosition.y
+          y: (map2.worldY ?? 0) - (nextMapInfo.y ?? 0) + nextPosition.y
         }));
       } else if (nextPosition.y < marginTopDown && direction === Direction.Up) {
         ret = await changeMap({
           x: worldPositionX,
-          y: (map.worldY ?? 0) - 1
+          y: (map2.worldY ?? 0) - 1
         }, (nextMapInfo) => ({
-          x: (map.worldX ?? 0) - (nextMapInfo.x ?? 0) + nextPosition.x,
+          x: (map2.worldX ?? 0) - (nextMapInfo.x ?? 0) + nextPosition.x,
           y: nextMapInfo.height - this.hitbox().h - marginTopDown
         }));
-      } else if (nextPosition.y > map.heightPx - this.hitbox().h - marginTopDown && direction === Direction.Down) {
+      } else if (nextPosition.y > map2.heightPx - this.hitbox().h - marginTopDown && direction === Direction.Down) {
         ret = await changeMap({
           x: worldPositionX,
-          y: (map.worldY ?? 0) + map.heightPx + 1
+          y: (map2.worldY ?? 0) + map2.heightPx + 1
         }, (nextMapInfo) => ({
-          x: (map.worldX ?? 0) - (nextMapInfo.x ?? 0) + nextPosition.x,
+          x: (map2.worldX ?? 0) - (nextMapInfo.x ?? 0) + nextPosition.x,
           y: marginTopDown
         }));
       } else {
@@ -22493,15 +23294,17 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
       this.x.set(positions.x);
       this.y.set(positions.y);
     }
-    this._frames.set(this.frames);
+    queueMicrotask(() => {
+      this.applyFrames();
+    });
   }
   getCurrentMap() {
     return this.map;
   }
   emit(type2, value) {
-    const map = this.getCurrentMap();
-    if (!map || !this.conn) return;
-    map.$send(this.conn, {
+    const map2 = this.getCurrentMap();
+    if (!map2 || !this.conn) return;
+    map2.$send(this.conn, {
       type: type2,
       value
     });
@@ -22544,12 +23347,12 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
    * ```
    */
   setAnimation(animationName, nbTimes = Infinity) {
-    const map = this.getCurrentMap();
-    if (!map) return;
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
     if (nbTimes === Infinity) {
       this.animationName.set(animationName);
     } else {
-      map.$broadcast({
+      map2.$broadcast({
         type: "setAnimation",
         value: {
           animationName,
@@ -22572,9 +23375,9 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     this._eventChanges();
   }
   databaseById(id) {
-    const map = this.getCurrentMap();
-    if (!map) return;
-    const data = map.database()[id];
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    const data = map2.database()[id];
     if (!data)
       throw new Error(
         `The ID=${id} data is not found in the database. Add the data in the property "database"`
@@ -22582,9 +23385,9 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     return data;
   }
   _eventChanges() {
-    const map = this.getCurrentMap();
-    if (!map) return;
-    const { events } = map;
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    const { events } = map2;
     const arrayEvents = [
       ...Object.values(this.events()),
       ...Object.values(events?.() ?? {})
@@ -22593,39 +23396,231 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
       if (event.onChanges) event.onChanges(this);
     }
   }
-  attachShape(id, options) {
-    const map = this.getCurrentMap();
-    if (!map) return;
-    const physic = map.physic;
-    const zoneId = physic.addZone(id, {
-      linkedTo: this.id,
-      ...options
-    });
-    physic.registerZoneEvents(
-      id,
-      (hitIds) => {
-        hitIds.forEach((id2) => {
-          const event = map.getEvent(id2);
-          const player = map.getPlayer(id2);
-          const zone = physic.getZone(zoneId);
-          if (event) {
-            event.execMethod("onInShape", [zone, this]);
-          }
-          if (player) this.execMethod("onDetectInShape", [player, zone]);
-        });
+  /**
+   * Attach a zone shape to this player using the physic zone system
+   * 
+   * This method creates a zone attached to the player's entity in the physics engine.
+   * The zone can be circular or cone-shaped and will detect other entities (players/events)
+   * entering or exiting the zone.
+   * 
+   * @param id - Optional zone identifier. If not provided, a unique ID will be generated
+   * @param options - Zone configuration options
+   * 
+   * @example
+   * ```ts
+   * // Create a circular detection zone
+   * player.attachShape("vision", {
+   *   radius: 150,
+   *   angle: 360,
+   * });
+   * 
+   * // Create a cone-shaped vision zone
+   * player.attachShape("vision", {
+   *   radius: 200,
+   *   angle: 120,
+   *   direction: Direction.Right,
+   *   limitedByWalls: true,
+   * });
+   * 
+   * // Create a zone with width/height (radius calculated automatically)
+   * player.attachShape({
+   *   width: 100,
+   *   height: 100,
+   *   positioning: "center",
+   * });
+   * ```
+   */
+  attachShape(idOrOptions, options) {
+    const map2 = this.getCurrentMap();
+    if (!map2) return void 0;
+    let zoneId;
+    let shapeOptions;
+    if (typeof idOrOptions === "string") {
+      zoneId = idOrOptions;
+      if (!options) {
+        console.warn("attachShape: options must be provided when id is specified");
+        return void 0;
+      }
+      shapeOptions = options;
+    } else {
+      zoneId = `zone-${this.id}-${Date.now()}`;
+      shapeOptions = idOrOptions;
+    }
+    const playerEntity = map2.physic.getEntityByUUID(this.id);
+    if (!playerEntity) {
+      console.warn(`Player entity not found in physic engine for player ${this.id}`);
+      return void 0;
+    }
+    let radius;
+    if (shapeOptions.radius !== void 0) {
+      radius = shapeOptions.radius;
+    } else if (shapeOptions.width && shapeOptions.height) {
+      radius = Math.max(shapeOptions.width, shapeOptions.height) / 2;
+    } else {
+      console.warn("attachShape: radius or width/height must be provided");
+      return void 0;
+    }
+    let offset = new Vector2(0, 0);
+    const positioning = shapeOptions.positioning || "default";
+    if (shapeOptions.positioning) {
+      const playerWidth = playerEntity.width || playerEntity.radius * 2 || 32;
+      const playerHeight = playerEntity.height || playerEntity.radius * 2 || 32;
+      switch (shapeOptions.positioning) {
+        case "top":
+          offset = new Vector2(0, -playerHeight / 2);
+          break;
+        case "bottom":
+          offset = new Vector2(0, playerHeight / 2);
+          break;
+        case "left":
+          offset = new Vector2(-playerWidth / 2, 0);
+          break;
+        case "right":
+          offset = new Vector2(playerWidth / 2, 0);
+          break;
+        case "center":
+        default:
+          offset = new Vector2(0, 0);
+          break;
+      }
+    }
+    const zoneManager = map2.physic.getZoneManager();
+    let direction = "down";
+    if (shapeOptions.direction !== void 0) {
+      if (typeof shapeOptions.direction === "string") {
+        direction = shapeOptions.direction;
+      } else {
+        direction = String(shapeOptions.direction);
+      }
+    }
+    const metadata = {};
+    if (shapeOptions.name) {
+      metadata.name = shapeOptions.name;
+    }
+    if (shapeOptions.properties) {
+      metadata.properties = shapeOptions.properties;
+    }
+    const initialX = playerEntity.position.x + offset.x;
+    const initialY = playerEntity.position.y + offset.y;
+    const physicZoneId = zoneManager.createAttachedZone(
+      playerEntity,
+      {
+        radius,
+        angle: shapeOptions.angle ?? 360,
+        direction,
+        limitedByWalls: shapeOptions.limitedByWalls ?? false,
+        offset,
+        metadata: Object.keys(metadata).length > 0 ? metadata : void 0
       },
-      (hitIds) => {
-        hitIds.forEach((id2) => {
-          const event = map.getEvent(id2);
-          const zone = physic.getZone(zoneId);
-          const player = map.getPlayer(id2);
-          if (event) {
-            event.execMethod("onOutShape", [zone, this]);
-          }
-          if (player) this.execMethod("onDetectOutShape", [player, zone]);
-        });
+      {
+        onEnter: (entities) => {
+          entities.forEach((entity) => {
+            const event = map2.getEvent(entity.uuid);
+            const player = map2.getPlayer(entity.uuid);
+            if (event) {
+              event.execMethod("onInShape", [shape, this]);
+              if (event._inShapes) {
+                event._inShapes.add(shape);
+              }
+            }
+            if (player) {
+              this.execMethod("onDetectInShape", [player, shape]);
+              if (player._inShapes) {
+                player._inShapes.add(shape);
+              }
+            }
+          });
+        },
+        onExit: (entities) => {
+          entities.forEach((entity) => {
+            const event = map2.getEvent(entity.uuid);
+            const player = map2.getPlayer(entity.uuid);
+            if (event) {
+              event.execMethod("onOutShape", [shape, this]);
+              if (event._inShapes) {
+                event._inShapes.delete(shape);
+              }
+            }
+            if (player) {
+              this.execMethod("onDetectOutShape", [player, shape]);
+              if (player._inShapes) {
+                player._inShapes.delete(shape);
+              }
+            }
+          });
+        }
       }
     );
+    const shape = new RpgShape({
+      name: shapeOptions.name || zoneId,
+      positioning,
+      width: shapeOptions.width || radius * 2,
+      height: shapeOptions.height || radius * 2,
+      x: initialX,
+      y: initialY,
+      properties: shapeOptions.properties || {},
+      playerOwner: this,
+      physicZoneId,
+      map: map2
+    });
+    this._zoneIdMap = this._zoneIdMap || /* @__PURE__ */ new Map();
+    this._zoneIdMap.set(zoneId, physicZoneId);
+    this._attachedShapes.set(zoneId, shape);
+    const updateShapePosition = () => {
+      const currentEntity = map2.physic.getEntityByUUID(this.id);
+      if (currentEntity) {
+        const zoneInfo = zoneManager.getZone(physicZoneId);
+        if (zoneInfo) {
+          shape._updatePosition(zoneInfo.position.x, zoneInfo.position.y);
+        }
+      }
+    };
+    playerEntity.onPositionChange(() => {
+      updateShapePosition();
+    });
+    return shape;
+  }
+  /**
+   * Get all shapes attached to this player
+   * 
+   * Returns all shapes that were created using `attachShape()` on this player.
+   * 
+   * @returns Array of RpgShape instances attached to this player
+   * 
+   * @example
+   * ```ts
+   * player.attachShape("vision", { radius: 150 });
+   * player.attachShape("detection", { radius: 100 });
+   * 
+   * const shapes = player.getShapes();
+   * console.log(shapes.length); // 2
+   * ```
+   */
+  getShapes() {
+    return Array.from(this._attachedShapes.values());
+  }
+  /**
+   * Get all shapes where this player is currently located
+   * 
+   * Returns all shapes (from any player/event) where this player is currently inside.
+   * This is updated automatically when the player enters or exits shapes.
+   * 
+   * @returns Array of RpgShape instances where this player is located
+   * 
+   * @example
+   * ```ts
+   * // Another player has a detection zone
+   * otherPlayer.attachShape("detection", { radius: 200 });
+   * 
+   * // Check if this player is in any shape
+   * const inShapes = player.getInShapes();
+   * if (inShapes.length > 0) {
+   *   console.log("Player is being detected!");
+   * }
+   * ```
+   */
+  getInShapes() {
+    return Array.from(this._inShapes);
   }
   /**
    * Show a temporary component animation on this player
@@ -22645,29 +23640,102 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
    *   color: "red"
    * });
    * 
-   * // Show a heal animation
-   * player.showComponentAnimation("heal", {
-   *   amount: 50
-   * });
+   * // Show a heal animation
+   * player.showComponentAnimation("heal", {
+   *   amount: 50
+   * });
+   * ```
+   */
+  showComponentAnimation(id, params = {}) {
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    map2.$broadcast({
+      type: "showComponentAnimation",
+      value: {
+        id,
+        params,
+        object: this.id
+      }
+    });
+  }
+  showHit(text) {
+    this.showComponentAnimation("hit", {
+      text,
+      direction: this.direction()
+    });
+  }
+  /**
+   * Play a sound on the client side for this player only
+   * 
+   * This method emits an event to play a sound only for this specific player.
+   * The sound must be defined on the client side (in the client module configuration).
+   * 
+   * ## Design
+   * 
+   * The sound is sent only to this player's client connection, making it ideal
+   * for personal feedback sounds like UI interactions, notifications, or personal
+   * achievements. For map-wide sounds that all players should hear, use `map.playSound()` instead.
+   * 
+   * @param soundId - Sound identifier, defined on the client side
+   * @param options - Optional sound configuration
+   * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+   * @param options.loop - Whether the sound should loop (default: false)
+   * 
+   * @example
+   * ```ts
+   * // Play a sound for this player only (default behavior)
+   * player.playSound("item-pickup");
+   * 
+   * // Play a sound with volume and loop
+   * player.playSound("background-music", {
+   *   volume: 0.5,
+   *   loop: true
+   * });
+   * 
+   * // Play a notification sound at low volume
+   * player.playSound("notification", { volume: 0.3 });
+   * ```
+   */
+  playSound(soundId, options) {
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    const data = {
+      soundId
+    };
+    if (options) {
+      if (options.volume !== void 0) {
+        data.volume = Math.max(0, Math.min(1, options.volume));
+      }
+      if (options.loop !== void 0) {
+        data.loop = options.loop;
+      }
+    }
+    this.emit("playSound", data);
+  }
+  /**
+   * Stop a sound that is currently playing for this player
+   * 
+   * This method stops a sound that was previously started with `playSound()`.
+   * The sound must be defined on the client side.
+   * 
+   * @param soundId - Sound identifier to stop
+   * 
+   * @example
+   * ```ts
+   * // Start a looping background music
+   * player.playSound("background-music", { loop: true });
+   * 
+   * // Later, stop it
+   * player.stopSound("background-music");
    * ```
    */
-  showComponentAnimation(id, params = {}) {
-    const map = this.getCurrentMap();
-    if (!map) return;
-    map.$broadcast({
-      type: "showComponentAnimation",
-      value: {
-        id,
-        params,
-        object: this.id
-      }
-    });
-  }
-  showHit(text) {
-    this.showComponentAnimation("hit", {
-      text,
-      direction: this.direction()
-    });
+  stopSound(soundId) {
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    const data = {
+      soundId
+    };
+    this.emit("stopSound", data);
   }
   /**
    * Set the sync schema for the map
@@ -22696,9 +23764,9 @@ class RpgEvent extends RpgPlayer {
     return ret;
   }
   remove() {
-    const map = this.getCurrentMap();
-    if (!map) return;
-    map.removeEvent(this.id);
+    const map2 = this.getCurrentMap();
+    if (!map2) return;
+    map2.removeEvent(this.id);
   }
 }
 
@@ -26027,12 +27095,126 @@ let RpgMap = class extends RpgCommonMap {
     this.dataIsReady$ = new BehaviorSubject$1(void 0);
     this.globalConfig = {};
     this.damageFormulas = {};
+    /** Internal: Map of shapes by name */
+    this._shapes = /* @__PURE__ */ new Map();
+    /** Internal: Map of shape entity UUIDs to RpgShape instances */
+    this._shapeEntities = /* @__PURE__ */ new Map();
     this.hooks.callHooks("server-map-onStart", this).subscribe();
     this.throttleSync = this.isStandalone ? 0 : 50;
     this.throttleStorage = this.isStandalone ? 0 : 1e3;
     this.sessionExpiryTime = 1e3 * 60 * 5;
+    this.setupCollisionDetection();
     this.loop();
   }
+  /**
+   * Setup collision detection between players, events, and shapes
+   * 
+   * This method listens to physics collision events and triggers hooks:
+   * - `onPlayerTouch` on events when a player collides with them
+   * - `onInShape` on players and events when they enter a shape
+   * - `onOutShape` on players and events when they exit a shape
+   * 
+   * ## Architecture
+   * 
+   * Uses the physics engine's collision event system to detect when entities collide.
+   * When a collision is detected:
+   * - Between a player and an event: triggers `onPlayerTouch` on the event
+   * - Between a player/event and a shape: triggers `onInShape`/`onOutShape` hooks
+   * 
+   * @example
+   * ```ts
+   * // Event with onPlayerTouch hook
+   * map.createDynamicEvent({
+   *   x: 100,
+   *   y: 200,
+   *   event: {
+   *     onPlayerTouch(player) {
+   *       console.log(`Player ${player.id} touched this event!`);
+   *     }
+   *   }
+   * });
+   * 
+   * // Player with onInShape hook
+   * const player: RpgPlayerHooks = {
+   *   onInShape(player: RpgPlayer, shape: RpgShape) {
+   *     console.log('in', player.name, shape.name);
+   *   },
+   *   onOutShape(player: RpgPlayer, shape: RpgShape) {
+   *     console.log('out', player.name, shape.name);
+   *   }
+   * };
+   * ```
+   */
+  setupCollisionDetection() {
+    const activeCollisions = /* @__PURE__ */ new Set();
+    const activeShapeCollisions = /* @__PURE__ */ new Set();
+    this.physic.getEvents().onCollisionEnter((collision) => {
+      const entityA = collision.entityA;
+      const entityB = collision.entityB;
+      const collisionKey = entityA.uuid < entityB.uuid ? `${entityA.uuid}-${entityB.uuid}` : `${entityB.uuid}-${entityA.uuid}`;
+      if (activeCollisions.has(collisionKey)) {
+        return;
+      }
+      const shapeA = this._shapeEntities.get(entityA.uuid);
+      const shapeB = this._shapeEntities.get(entityB.uuid);
+      if (shapeA || shapeB) {
+        const shape = shapeA || shapeB;
+        const otherEntity = shapeA ? entityB : entityA;
+        if (shape) {
+          const shapeKey = `${otherEntity.uuid}-${shape.name}`;
+          if (!activeShapeCollisions.has(shapeKey)) {
+            activeShapeCollisions.add(shapeKey);
+            const player2 = this.getPlayer(otherEntity.uuid);
+            const event2 = this.getEvent(otherEntity.uuid);
+            if (player2) {
+              player2.execMethod("onInShape", [player2, shape]);
+            }
+            if (event2) {
+              event2.execMethod("onInShape", [shape, player2 || event2]);
+            }
+          }
+        }
+        return;
+      }
+      const player = this.getPlayer(entityA.uuid) || this.getPlayer(entityB.uuid);
+      if (!player) {
+        return;
+      }
+      const eventId = player.id === entityA.uuid ? entityB.uuid : entityA.uuid;
+      const event = this.getEvent(eventId);
+      if (event) {
+        activeCollisions.add(collisionKey);
+        event.execMethod("onPlayerTouch", [player]);
+      }
+    });
+    this.physic.getEvents().onCollisionExit((collision) => {
+      const entityA = collision.entityA;
+      const entityB = collision.entityB;
+      const collisionKey = entityA.uuid < entityB.uuid ? `${entityA.uuid}-${entityB.uuid}` : `${entityB.uuid}-${entityA.uuid}`;
+      const shapeA = this._shapeEntities.get(entityA.uuid);
+      const shapeB = this._shapeEntities.get(entityB.uuid);
+      if (shapeA || shapeB) {
+        const shape = shapeA || shapeB;
+        const otherEntity = shapeA ? entityB : entityA;
+        if (shape) {
+          const shapeKey = `${otherEntity.uuid}-${shape.name}`;
+          if (activeShapeCollisions.has(shapeKey)) {
+            activeShapeCollisions.delete(shapeKey);
+            const player = this.getPlayer(otherEntity.uuid);
+            const event = this.getEvent(otherEntity.uuid);
+            if (player) {
+              player.execMethod("onOutShape", [player, shape]);
+            }
+            if (event) {
+              event.execMethod("onOutShape", [shape, player || event]);
+            }
+          }
+        }
+        return;
+      }
+      activeCollisions.delete(collisionKey);
+    });
+  }
   // autoload by @signe/room
   interceptorPacket(player, packet, conn) {
     let obj = {};
@@ -26069,7 +27251,6 @@ let RpgMap = class extends RpgCommonMap {
     player._onInit();
     this.dataIsReady$.pipe(
       finalize$1(() => {
-        player.applyFrames();
         this.hooks.callHooks("server-player-onJoinMap", player, this).subscribe();
       })
     ).subscribe();
@@ -26189,8 +27370,16 @@ let RpgMap = class extends RpgCommonMap {
    * This method processes all pending inputs for a player while performing
    * anti-cheat validation to prevent time manipulation and frame skipping.
    * It validates the time deltas between inputs and ensures they are within
-   * acceptable ranges. After processing, it saves the last frame position
-   * for use in packet interception.
+   * acceptable ranges.
+   * 
+   * ## Architecture
+   * 
+   * **Important**: This method only updates entity velocities - it does NOT step
+   * the physics engine. Physics simulation is handled centrally by the game loop
+   * (`tick$` -> `runFixedTicks`). This ensures:
+   * - Consistent physics timing (60fps fixed timestep)
+   * - No double-stepping when multiple inputs are processed
+   * - Deterministic physics regardless of input frequency
    * 
    * @param playerId - The ID of the player to process inputs for
    * @param controls - Optional anti-cheat configuration
@@ -26272,7 +27461,6 @@ let RpgMap = class extends RpgCommonMap {
       lastProcessedFrame = input.frame;
     }
     if (hasProcessedInputs) {
-      this.forceSingleTick();
       player.lastProcessedInputTs = lastProcessedTime;
     } else {
       const idleTimeout = Math.max(config.minTimeBetweenInputs * 4, 50);
@@ -26282,7 +27470,6 @@ let RpgMap = class extends RpgCommonMap {
         player.lastProcessedInputTs = 0;
       }
     }
-    player.applyFrames();
     return {
       player,
       inputs: processedInputs
@@ -26419,7 +27606,6 @@ let RpgMap = class extends RpgCommonMap {
     eventInstance.context = context$1;
     eventInstance.x.set(x);
     eventInstance.y.set(y);
-    eventInstance.applyFrames();
     if (event.name) eventInstance.name.set(event.name);
     this.events()[id] = eventInstance;
     await eventInstance.execMethod("onInit");
@@ -26544,6 +27730,277 @@ let RpgMap = class extends RpgCommonMap {
       }, holder);
     }
   }
+  /**
+   * Create a shape dynamically on the map
+   * 
+   * This method creates a static hitbox on the map that can be used for
+   * collision detection, area triggers, or visual boundaries. The shape is
+   * backed by the physics engine's static entity system for accurate collision detection.
+   * 
+   * ## Architecture
+   * 
+   * Creates a static entity (hitbox) in the physics engine at the specified position and size.
+   * The shape is stored internally and can be retrieved by name. When players or events
+   * collide with this hitbox, the `onInShape` and `onOutShape` hooks are automatically
+   * triggered on both the player and the event.
+   * 
+   * @param obj - Shape configuration object
+   * @param obj.x - X position of the shape (top-left corner) (required)
+   * @param obj.y - Y position of the shape (top-left corner) (required)
+   * @param obj.width - Width of the shape in pixels (required)
+   * @param obj.height - Height of the shape in pixels (required)
+   * @param obj.name - Name of the shape (optional, auto-generated if not provided)
+   * @param obj.z - Z position/depth for rendering (optional)
+   * @param obj.color - Color in hexadecimal format, shared with client (optional)
+   * @param obj.collision - Whether the shape has collision (optional)
+   * @param obj.properties - Additional custom properties (optional)
+   * @returns The created RpgShape instance
+   * 
+   * @example
+   * ```ts
+   * // Create a simple rectangular shape
+   * const shape = map.createShape({
+   *   x: 100,
+   *   y: 200,
+   *   width: 50,
+   *   height: 50,
+   *   name: "spawn-zone"
+   * });
+   * 
+   * // Create a shape with visual properties
+   * const triggerZone = map.createShape({
+   *   x: 300,
+   *   y: 400,
+   *   width: 100,
+   *   height: 100,
+   *   name: "treasure-area",
+   *   color: "#FFD700",
+   *   z: 1,
+   *   collision: false,
+   *   properties: {
+   *     type: "treasure",
+   *     value: 100
+   *   }
+   * });
+   * 
+   * // Player hooks will be triggered automatically
+   * const player: RpgPlayerHooks = {
+   *   onInShape(player: RpgPlayer, shape: RpgShape) {
+   *     console.log('in', player.name, shape.name);
+   *   },
+   *   onOutShape(player: RpgPlayer, shape: RpgShape) {
+   *     console.log('out', player.name, shape.name);
+   *   }
+   * };
+   * ```
+   */
+  createShape(obj) {
+    const { x, y, width, height } = obj;
+    if (typeof x !== "number" || typeof y !== "number") {
+      throw new Error("Shape x and y must be numbers");
+    }
+    if (typeof width !== "number" || width <= 0) {
+      throw new Error("Shape width must be a positive number");
+    }
+    if (typeof height !== "number" || height <= 0) {
+      throw new Error("Shape height must be a positive number");
+    }
+    const name = obj.name || generateShortUUID$2();
+    if (this._shapes.has(name)) {
+      throw new Error(`Shape with name "${name}" already exists`);
+    }
+    const centerX = x + width / 2;
+    const centerY = y + height / 2;
+    const entityId = `shape-${name}`;
+    const entity = this.physic.createEntity({
+      uuid: entityId,
+      position: { x: centerX, y: centerY },
+      width,
+      height,
+      mass: Infinity,
+      // Static entity
+      state: EntityState.Static,
+      restitution: 0
+      // No bounce
+    });
+    entity.freeze();
+    const properties = {
+      ...obj.properties || {}
+    };
+    if (obj.z !== void 0) properties.z = obj.z;
+    if (obj.color !== void 0) properties.color = obj.color;
+    if (obj.collision !== void 0) properties.collision = obj.collision;
+    const shape = new RpgShape({
+      name,
+      positioning: "default",
+      width,
+      height,
+      x: centerX,
+      y: centerY,
+      properties,
+      playerOwner: void 0,
+      // Static shapes are not attached to players
+      physicZoneId: entityId,
+      // Store entity UUID for reference
+      map: this
+    });
+    this._shapes.set(name, shape);
+    this._shapeEntities.set(entityId, shape);
+    return shape;
+  }
+  /**
+   * Delete a shape from the map
+   * 
+   * Removes a shape by its name and cleans up the associated static hitbox entity.
+   * If the shape doesn't exist, the method does nothing.
+   * 
+   * @param name - Name of the shape to remove
+   * @returns void
+   * 
+   * @example
+   * ```ts
+   * // Create and then remove a shape
+   * const shape = map.createShape({
+   *   x: 100,
+   *   y: 200,
+   *   width: 50,
+   *   height: 50,
+   *   name: "temp-zone"
+   * });
+   * 
+   * // Later, remove it
+   * map.removeShape("temp-zone");
+   * ```
+   */
+  removeShape(name) {
+    const shape = this._shapes.get(name);
+    if (!shape) {
+      return;
+    }
+    const entityId = shape._physicZoneId;
+    const entity = this.physic.getEntityByUUID(entityId);
+    if (entity) {
+      this.physic.removeEntity(entity);
+    }
+    this._shapes.delete(name);
+    this._shapeEntities.delete(entityId);
+  }
+  /**
+   * Get all shapes on the map
+   * 
+   * Returns an array of all shapes that have been created on this map,
+   * regardless of whether they are static shapes or player-attached shapes.
+   * 
+   * @returns Array of RpgShape instances
+   * 
+   * @example
+   * ```ts
+   * // Create multiple shapes
+   * map.createShape({ x: 0, y: 0, width: 50, height: 50, name: "zone1" });
+   * map.createShape({ x: 100, y: 100, width: 50, height: 50, name: "zone2" });
+   * 
+   * // Get all shapes
+   * const allShapes = map.getShapes();
+   * console.log(allShapes.length); // 2
+   * ```
+   */
+  getShapes() {
+    return Array.from(this._shapes.values());
+  }
+  /**
+   * Get a shape by its name
+   * 
+   * Returns a shape with the specified name, or undefined if no shape
+   * with that name exists on the map.
+   * 
+   * @param name - Name of the shape to retrieve
+   * @returns The RpgShape instance, or undefined if not found
+   * 
+   * @example
+   * ```ts
+   * // Create a shape with a specific name
+   * map.createShape({
+   *   x: 100,
+   *   y: 200,
+   *   width: 50,
+   *   height: 50,
+   *   name: "spawn-point"
+   * });
+   * 
+   * // Retrieve it later
+   * const spawnZone = map.getShape("spawn-point");
+   * if (spawnZone) {
+   *   console.log(`Spawn zone at (${spawnZone.x}, ${spawnZone.y})`);
+   * }
+   * ```
+   */
+  getShape(name) {
+    return this._shapes.get(name);
+  }
+  /**
+   * Play a sound for all players on the map
+   * 
+   * This method plays a sound for all players currently on the map by iterating
+   * over each player and calling `player.playSound()`. The sound must be defined
+   * on the client side (in the client module configuration).
+   * This is ideal for environmental sounds, battle music, or map-wide events that
+   * all players should hear simultaneously.
+   * 
+   * ## Design
+   * 
+   * Iterates over all players on the map and calls `player.playSound()` for each one.
+   * This avoids code duplication and reuses the existing player sound logic.
+   * For player-specific sounds, use `player.playSound()` directly.
+   * 
+   * @param soundId - Sound identifier, defined on the client side
+   * @param options - Optional sound configuration
+   * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+   * @param options.loop - Whether the sound should loop (default: false)
+   * 
+   * @example
+   * ```ts
+   * // Play a sound for all players on the map
+   * map.playSound("explosion");
+   * 
+   * // Play background music for everyone with volume and loop
+   * map.playSound("battle-theme", {
+   *   volume: 0.7,
+   *   loop: true
+   * });
+   * 
+   * // Play a door opening sound at low volume
+   * map.playSound("door-open", { volume: 0.4 });
+   * ```
+   */
+  playSound(soundId, options) {
+    const players = this.getPlayers();
+    players.forEach((player) => {
+      player.playSound(soundId, options);
+    });
+  }
+  /**
+   * Stop a sound for all players on the map
+   * 
+   * This method stops a sound that was previously started with `map.playSound()`
+   * for all players on the map by iterating over each player and calling `player.stopSound()`.
+   * 
+   * @param soundId - Sound identifier to stop
+   * 
+   * @example
+   * ```ts
+   * // Start background music for everyone
+   * map.playSound("battle-theme", { loop: true });
+   * 
+   * // Later, stop it for everyone
+   * map.stopSound("battle-theme");
+   * ```
+   */
+  stopSound(soundId) {
+    const players = this.getPlayers();
+    players.forEach((player) => {
+      player.stopSound(soundId);
+    });
+  }
 };
 __decorateClass$1([
   users$1(RpgPlayer)
@@ -26646,6 +28103,234 @@ function createServer(options) {
   };
 }
 
+const Components = {
+  /**
+   * Create a text component
+   * 
+   * Creates a text component that displays text with optional styling.
+   * Supports template strings with placeholders like {name}, {hp}, etc.
+   * that are replaced with actual player property values.
+   * 
+   * ## Design
+   * 
+   * Text components use template strings to allow dynamic content without
+   * resending the entire component structure when values change. Only the
+   * property values are synchronized, reducing bandwidth usage.
+   * 
+   * @param text - Text to display, can include placeholders like {name}, {hp}
+   * @param options - Text styling options
+   * @returns Component definition for text
+   * 
+   * @example
+   * ```ts
+   * // Simple text
+   * Components.text('Player Name');
+   * 
+   * // Text with placeholder
+   * Components.text('{name}');
+   * 
+   * // Text with styling
+   * Components.text('{name}', {
+   *   fill: '#000000',
+   *   fontSize: 20
+   * });
+   * ```
+   */
+  text(value, style) {
+    return {
+      type: "text",
+      value,
+      style
+    };
+  },
+  /**
+   * Create an HP bar component
+   * 
+   * Creates a health point bar that automatically displays the player's
+   * current HP relative to their maximum HP. The bar updates automatically
+   * as HP changes.
+   * 
+   * ## Design
+   * 
+   * HP bars read from the player's hp and param.maxHp properties. The
+   * bar can optionally display text above it showing current, max, or
+   * percentage values.
+   * 
+   * @param options - Bar styling options
+   * @param text - Optional text to display above the bar. Can use placeholders:
+   *   - {$current} - Current HP value
+   *   - {$max} - Maximum HP value
+   *   - {$percent} - Percentage value
+   *   Set to null to hide text
+   * @returns Component definition for HP bar
+   * 
+   * @example
+   * ```ts
+   * // Simple HP bar
+   * Components.hpBar();
+   * 
+   * // HP bar with percentage text
+   * Components.hpBar({}, '{$percent}%');
+   * 
+   * // HP bar with custom styling
+   * Components.hpBar({
+   *   fillColor: '#ff0000',
+   *   height: 8
+   * });
+   * ```
+   */
+  hpBar(style, text) {
+    return {
+      type: "hpBar",
+      style,
+      text: text ?? void 0
+    };
+  },
+  /**
+   * Create an SP bar component
+   * 
+   * Creates a skill point bar that automatically displays the player's
+   * current SP relative to their maximum SP. The bar updates automatically
+   * as SP changes.
+   * 
+   * @param style - Bar styling options
+   * @param text - Optional text to display above the bar. Can use placeholders:
+   *   - {$current} - Current SP value
+   *   - {$max} - Maximum SP value
+   *   - {$percent} - Percentage value
+   *   Set to null to hide text
+   * @returns Component definition for SP bar
+   * 
+   * @example
+   * ```ts
+   * // Simple SP bar
+   * Components.spBar();
+   * 
+   * // SP bar with text
+   * Components.spBar({}, 'SP: {$current}/{$max}');
+   * ```
+   */
+  spBar(style, text) {
+    return {
+      type: "spBar",
+      style,
+      text: text ?? void 0
+    };
+  },
+  /**
+   * Create a custom bar component
+   * 
+   * Creates a bar that displays a custom property value relative to a maximum.
+   * Useful for displaying custom resources like wood, mana, energy, etc.
+   * 
+   * @param current - Property path for current value (e.g., 'wood', 'mana')
+   * @param max - Property path for maximum value (e.g., 'param.maxWood', 'param.maxMana')
+   * @param style - Bar styling options
+   * @param text - Optional text to display above the bar. Can use placeholders:
+   *   - {$current} - Current value
+   *   - {$max} - Maximum value
+   *   - {$percent} - Percentage value
+   *   Set to null to hide text
+   * @returns Component definition for custom bar
+   * 
+   * @example
+   * ```ts
+   * // Bar for custom property
+   * Components.bar('wood', 'param.maxWood');
+   * 
+   * // Bar with text
+   * Components.bar('mana', 'param.maxMana', {}, 'Mana: {$current}/{$max}');
+   * ```
+   */
+  bar(current, max, style, text) {
+    return {
+      type: "bar",
+      current,
+      max,
+      style,
+      text: text ?? void 0
+    };
+  },
+  /**
+   * Create a shape component
+   * 
+   * Creates a geometric shape that can be displayed above or below the player.
+   * Useful for visual indicators, backgrounds, or decorative elements.
+   * 
+   * @param value - Shape configuration options
+   * @returns Component definition for shape
+   * 
+   * @example
+   * ```ts
+   * // Circle shape
+   * Components.shape({
+   *   fill: '#ffffff',
+   *   type: 'circle',
+   *   radius: 10
+   * });
+   * 
+   * // Rectangle shape
+   * Components.shape({
+   *   fill: '#ff0000',
+   *   type: 'rectangle',
+   *   width: 32,
+   *   height: 32
+   * });
+   * 
+   * // Using parameters
+   * Components.shape({
+   *   fill: '#ffffff',
+   *   type: 'circle',
+   *   radius: 'hp' // radius will be the same as hp value
+   * });
+   * ```
+   */
+  shape(value) {
+    return {
+      type: "shape",
+      value
+    };
+  },
+  /**
+   * Create an image component
+   * 
+   * Displays an image from a URL or spritesheet identifier.
+   * 
+   * @param value - Image source URL or spritesheet identifier
+   * @returns Component definition for image
+   * 
+   * @example
+   * ```ts
+   * Components.image('mygraphic.png');
+   * ```
+   */
+  image(value) {
+    return {
+      type: "image",
+      value
+    };
+  },
+  /**
+   * Create a tile component
+   * 
+   * Displays a tile from a tileset by ID.
+   * 
+   * @param value - Tile ID in the tileset
+   * @returns Component definition for tile
+   * 
+   * @example
+   * ```ts
+   * Components.tile(3); // Use tile #3
+   * ```
+   */
+  tile(value) {
+    return {
+      type: "tile",
+      value
+    };
+  }
+};
+
 function provideServerModules(modules) {
   return provideModules(modules, "server", (modules2, context) => {
     const mainModuleServer = findModules(context, "Server");
@@ -26696,5 +28381,5 @@ function provideServerModules(modules) {
   });
 }
 
-export { AGI, AGI_CURVE, ATK, ArraySubject$1 as ArraySubject, COEFFICIENT_ELEMENTS, DAMAGE_CRITICAL, DAMAGE_GUARD, DAMAGE_PHYSIC, DAMAGE_SKILL, DEX, DEX_CURVE, DialogGui, DialogPosition, Frequency, Gui, INT, INT_CURVE, MAXHP, MAXHP_CURVE, MAXSP, MAXSP_CURVE, MenuGui, Move, NotificationGui, ObjectSubject$1 as ObjectSubject, PDEF, RpgEvent, RpgMap, RpgPlayer, RpgServerEngine, SDEF, STR, STR_CURVE, ShopGui, Speed, WithMoveManager, clearInject, computed$1 as computed, context, createServer, effect$1 as effect, inject, isArraySubject$1 as isArraySubject, isComputed$1 as isComputed, isObjectSubject$1 as isObjectSubject, isSignal$1 as isSignal, provideServerModules, setInject, signal$1 as signal, untracked$1 as untracked };
+export { AGI, AGI_CURVE, ATK, ArraySubject$1 as ArraySubject, COEFFICIENT_ELEMENTS, Components, DAMAGE_CRITICAL, DAMAGE_GUARD, DAMAGE_PHYSIC, DAMAGE_SKILL, DEX, DEX_CURVE, DialogGui, DialogPosition, Frequency, Gui, INT, INT_CURVE, MAXHP, MAXHP_CURVE, MAXSP, MAXSP_CURVE, MenuGui, Move, NotificationGui, ObjectSubject$1 as ObjectSubject, PDEF, RpgEvent, RpgMap, RpgPlayer, RpgServerEngine, RpgShape, SDEF, STR, STR_CURVE, ShopGui, Speed, WithMoveManager, clearInject, computed$1 as computed, context, createServer, effect$1 as effect, inject, isArraySubject$1 as isArraySubject, isComputed$1 as isComputed, isObjectSubject$1 as isObjectSubject, isSignal$1 as isSignal, provideServerModules, setInject, signal$1 as signal, untracked$1 as untracked };
 //# sourceMappingURL=index.js.map