feat: billboard target entity new prop

ai-sdk-context/sdk7-complete-reference.md

@@ -394,6 +394,14 @@ BillboardMode.BM_NONE // No rotation
 BillboardMode.BM_X // Fixed X axis
 BillboardMode.BM_Y // Fixed Y axis (most common)
 BillboardMode.BM_Z // Fixed Z axis
+
+// Face another entity instead of the player's camera
+Billboard.create(entity, {
+	targetEntity: otherEntity, // optional; unset = face the camera
+})
+// If the target entity doesn't exist (not yet created, or removed), the
+// billboard keeps its last orientation until the target exists again.
+// targetEntity: engine.CameraEntity is equivalent to leaving it unset.
 ```
 
 #### Face Target

contributor-esp/runtime/basic-components.md

@@ -80,9 +80,9 @@ Como el modelo tiene sus propias mallas y materiales, este componente anula cual
 
 ##### `Billboard` <small>[↗ source](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17)</small> {#Billboard}
 
-Hace que una Entidad reoriente automáticamente su `Transform` para enfrentar la cámara. Como el nombre indica, se usa para mostrar billboards en el juego y frecuentemente se combina con [`TextShape`](#TextShape).
+Hace que una Entidad reoriente automáticamente su `Transform` para enfrentar la cámara, u opcionalmente otra Entidad referenciada mediante `target_entity`. Como el nombre indica, se usa para mostrar billboards en el juego y frecuentemente se combina con [`TextShape`](#TextShape).
 
-Afecta todas las direcciones por defecto, pero puede configurarse para rotar solo en un eje.
+Afecta todas las direcciones por defecto, pero puede configurarse para rotar solo en un eje. Si la Entidad objetivo referenciada no existe, la reorientación se suspende hasta que exista.
 
 ---
 

contributor/runtime/basic-components.md

@@ -80,9 +80,9 @@ Since the model has its own meshes and materials, this component overrides any b
 
 ##### `Billboard` <small>[↗ source](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17)</small> {#Billboard}
 
-Makes an Entity automatically reorient its `Transform` to face the camera. As the name indicates, it's used to display in-game billboards and frequently combined with [`TextShape`](#TextShape).
+Makes an Entity automatically reorient its `Transform` to face the camera, or optionally another Entity referenced via `target_entity`. As the name indicates, it's used to display in-game billboards and frequently combined with [`TextShape`](#TextShape).
 
-It affects all directions by default, but can be set to only rotate in one axis.
+It affects all directions by default, but can be set to only rotate in one axis. If the referenced target Entity doesn't exist, reorientation is suspended until it does.
 
 ---
 

creator-esp/sdk7/3d-essentials/entity-positioning.md

@@ -177,6 +177,8 @@ Puedes configurar cómo se comporta el billboard con los siguientes parámetros:
   * `BillboardMode.BM_Y`: La entidad tiene su eje de rotación _y_ fijo. Solo rota hacia la izquierda y derecha, no arriba y abajo. Permanece perpendicular al suelo si el jugador está encima o debajo de la entidad.
   * `BillboardMode.BM_Z`: La entidad tiene su eje de rotación _z_ fijo.
 
+* `targetEntity`: (opcional) Una entidad hacia la cual rota el billboard, en lugar de la cámara del jugador. Si la entidad referenciada no existe (por ejemplo, todavía no fue creada o fue eliminada), el billboard deja de rotar y mantiene su última orientación hasta que la entidad exista nuevamente. Asignarle `engine.CameraEntity` es equivalente a no asignar el campo.
+
 ```ts
 // billboard plano
 const perpendicularPlane = engine.addEntity()
@@ -203,6 +205,29 @@ TextShape.create(textLabel, {
 })
 
 Billboard.create(textLabel)
+
+// cartel que mira a otra entidad en lugar del jugador
+const sphere = engine.addEntity()
+
+Transform.create(sphere, {
+	position: Vector3.create(4, 2, 4),
+})
+
+MeshRenderer.setSphere(sphere)
+
+const sign = engine.addEntity()
+
+Transform.create(sign, {
+	position: Vector3.create(8, 1, 8),
+})
+
+TextShape.create(sign, {
+	text: 'Mirando la esfera',
+})
+
+Billboard.create(sign, {
+	targetEntity: sphere,
+})
 ```
 
 {% hint style="info" %}
@@ -214,7 +239,7 @@ El valor de `rotation` del componente `Transform` de la entidad no cambia a medi
 Si una entidad tiene tanto un componente `Billboard` como un componente `Transform` con valores de `rotation`, los jugadores verán la entidad rotando como un billboard. Si el billboard no afecta todos los ejes, el eje restante se rotará de acuerdo con el componente `Transform`.
 
 {% hint style="warning" %}
-**📔 Nota**: Si hay varios jugadores presentes al mismo tiempo, cada uno verá las entidades con modo billboard mirándolos. Las rotaciones de billboard se calculan localmente para cada jugador y no afectan lo que ven los demás.
+**📔 Nota**: Si hay varios jugadores presentes al mismo tiempo, cada uno verá las entidades con modo billboard mirándolos. Las rotaciones de billboard se calculan localmente para cada jugador y no afectan lo que ven los demás. Esto no aplica a los billboards con `targetEntity`: como la posición del objetivo es parte de la escena, todos los jugadores ven esos billboards orientados de la misma manera.
 {% endhint %}
 
 ## Mirar un conjunto de coordenadas

creator/sdk7/3d-essentials/entity-positioning.md

@@ -195,6 +195,8 @@ You can configure how the billboard behaves with the following parameters:
   * `BillboardMode.BM_Y`: The entity has its _y_ rotation axis fixed. It only rotates left and right, not up and down. It stays perpendicular to the ground if the player is above or below the entity.
   * `BillboardMode.BM_Z`: The entity has its _z_ rotation axis fixed.
 
+* `targetEntity`: (optional) An entity that the billboard rotates to face, instead of the player's camera. If the referenced entity doesn't exist (for example, it hasn't been created yet or it was removed), the billboard stops rotating and keeps its last orientation until the entity exists again. Setting this to `engine.CameraEntity` is equivalent to leaving it unset.
+
 ```ts
 // flat billboard
 const perpendicularPlane = engine.addEntity()
@@ -221,6 +223,29 @@ TextShape.create(textLabel, {
 })
 
 Billboard.create(textLabel)
+
+// sign that faces another entity instead of the player
+const sphere = engine.addEntity()
+
+Transform.create(sphere, {
+	position: Vector3.create(4, 2, 4),
+})
+
+MeshRenderer.setSphere(sphere)
+
+const sign = engine.addEntity()
+
+Transform.create(sign, {
+	position: Vector3.create(8, 1, 8),
+})
+
+TextShape.create(sign, {
+	text: 'Watching the sphere',
+})
+
+Billboard.create(sign, {
+	targetEntity: sphere,
+})
 ```
 
 {% hint style="info" %}
@@ -232,7 +257,7 @@ The `rotation` value of the entity's `Transform` component doesn't change as the
 If an entity has both a `Billboard` component and `Transform` component with `rotation` values, players will see the entity rotating as a billboard. If the billboard doesn't affect all axis, the remaining axis will be rotated according to the `Transform` component.
 
 {% hint style="warning" %}
-**📔 Note**: If there are multiple players present at the same time, each will see the entities with billboard mode facing them. Billboard rotations are calculated locally for each player, and don't affect what others see.
+**📔 Note**: If there are multiple players present at the same time, each will see the entities with billboard mode facing them. Billboard rotations are calculated locally for each player, and don't affect what others see. This doesn't apply to billboards with a `targetEntity`: since the target's position is part of the scene, all players see those billboards facing the same way.
 {% endhint %}
 
 ## Face a set of coordinates