Objetos y escenas
Todo en tu proyecto se construye con dos ideas: cosas hechas de componentes, y escenas que deciden cuándo aparecen esas cosas. Esta página trata de ambas.
El editor los llama objetos, porque es a lo que se parecen en pantalla. El motor y la API de scripting los llaman entities. No hay diferencia: esta página usa entity donde importa distinguirlos de los componentes, y objeto en todo lo demás.
Dos relaciones, y no son la misma
Casi todos los malentendidos con este motor vienen de mezclar dos cosas que parecen ambas «dentro».
Una entity está HECHA DE componentes. Los componentes no son hijos: son las partes que deciden lo que la entity es. Uno de cada clase, como mucho.
Entity "Lámpara"
├── Meta su nombre, si está activada, si es visible
├── Transform dónde está, cómo está girada, qué tamaño tiene
├── Model qué modelo 3D dibujar
└── Events a qué reacciona
Una entity puede CONTENER otras entities. Esas son hijas, y son entities por derecho propio, cada una con sus propios componentes.
Entity "Lámpara"
└── Entity "Bombilla" ← una entity aparte…
├── Transform ← …con sus propios componentes
└── Light
Juntas, una escena real tiene este aspecto: los componentes a la izquierda de cada entity, las hijas sangradas debajo.
Entity "Salón" ◆ Anchor ← esta es una ESCENA: tiene anclaje
│
├── Entity "Lámpara" ◆ Transform ◆ Model ◆ Events
│ └── Entity "Bombilla" ◆ Transform ◆ Light
│
└── Entity "Mesa" ◆ Transform ◆ Model ◆ RigidBody ◆ Collider
Todo lo de esa imagen es la misma clase de cosa: una entity. Lo que hace que una sea escena, otra lámpara y otra cuerpo físico es solo qué componentes lleva.
Mover la lámpara mueve la bombilla, porque la bombilla está dentro. Quitarle a la lámpara su componente de modelo no quita la bombilla: eso es composición, no contención.
Si alguna vez te preguntas «¿esto debería ser un componente o un objeto hijo?», la respuesta es: un componente cuando es un aspecto de esta cosa; un hijo cuando es una cosa aparte que debe moverse con ella.
Una entity es lo que digan sus componentes
No hay un menú de tipos de objeto donde elegir. Construyes lo que necesitas combinando componentes:
| Dale a una entity… | …y obtienes |
|---|---|
| geometría + material | una forma visible |
| una referencia a un modelo | un modelo 3D importado |
| un componente de luz | una luz |
| un componente de texto | un texto |
| un cuerpo rígido + un collider | algo que la física puede mover |
| un anclaje | una escena |
| un script o un patch | algo con comportamiento |
Digamos que quieres una pelota que rebote. Empieza con una esfera y un material: ya se ve. Añade un cuerpo rígido y un collider, y ahora cae y rebota. Añade un script, y ahora hace algo al aterrizar. Cada componente añade una capacidad, y quitarlo se la lleva otra vez.
Las tres formas con las que te encontrarás
El mismo modelo de entity produce tres cosas que se sienten distintas y no lo son:
| Qué es | Tiene | No tiene |
|---|---|---|
| Una escena | un anclaje e hijos | un transform |
| Un objeto normal | un transform, más lo que necesite | un anclaje |
| Comportamiento a nivel de space | un script o un patch, y ningún padre | transform, anclaje |
Una escena no tiene transform porque no tiene dónde estar: su posición viene de la cosa real a la que está anclada. Un portador a nivel de space no lo tiene porque no está en el mundo en absoluto: es solo lógica que sigue corriendo.
¿Necesitas tres materiales en un modelo? Usa los slots de su único componente de material. ¿Necesitas dos de cualquier otra cosa? Usa entities hijas: una lámpara con dos bombillas es una entity lámpara con dos hijos.
Toda entity tiene además un nombre (así la encuentras) y un padre.
Activado y visible son cosas distintas
Se parecen en el inspector y no se comportan igual en nada.
Desactivado saca la entity de la experiencia en marcha. No se dibuja, no se puede tocar, sus scripts se detienen, sus eventos callan. Como si no estuviera.
Invisible solo impide que se dibuje y se toque. Sigue ahí: los scripts corren, la física sigue chocando.
Así que: ¿un muro invisible con el que el jugador aún tropieza? Invisible. ¿Un premio que aparece más tarde? Desactivado hasta que lo necesites.
Padres e hijos
Las entities forman un árbol. Mueve un padre y sus hijos van con él, conservando sus posiciones relativas, que es como se construye todo lo que tiene piezas. Una carrocería con cuatro ruedas emparentadas se mueve como un solo coche.
Una entity sin padre está en la raíz de su escena.
Los hijos también, y sus hijos. Saca uno fuera primero si quieres conservarlo.
No puedes hacer que una entity sea hija de su propio descendiente: el editor se niega en vez de enredar el árbol.
Escenas y anclajes
Una escena es una entity con un anclaje, y el anclaje responde a una pregunta: ¿cuándo debe aparecer esto?
| Anclaje | Tu escena aparece cuando… |
|---|---|
image | la cámara reconoce una imagen impresa |
qr | se escanea un código QR |
geo | el visitante está en un lugar |
face | se detecta una cara |
surface | el visitante la coloca en un suelo, pared, techo o mesa |
panorama | se abre un entorno de 360° |
3d | al instante — una escena 3D normal, sin AR de por medio |
Posicionarse contra un mapa escaneado de un lugar real es una opción del anclaje surface, no un tipo aparte. Monta una escena surface y luego activa el VPS.
Varias escenas, un marcador
Las escenas que comparten disparador (la misma imagen, el mismo código QR, el mismo lugar) forman un grupo, y solo se muestra una escena del grupo a la vez.
Así funciona una historia: el mismo cartel abre el primer capítulo y más tarde el segundo, porque cambiaste cuál de las escenas del grupo está activa.
Mostrar y ocultar al detectar es simplemente un par de eventos que el editor monta por ti
(on-detect muestra, on-lost oculta). Son eventos normales, así que puedes cambiarlos — por
ejemplo para mantener el contenido en pantalla después de que el marcador salga del encuadre, que
es lo que los visitantes suelen preferir frente a un contenido que desaparece al menor temblor de
mano.
Las escenas surface tienen tres ajustes separados
Se confunden mucho, así que aquí están uno al lado del otro:
- Qué superficies aceptar: suelo, pared, techo, mesa.
- Cómo se coloca el contenido: automáticamente sobre una superficie detectada, o donde el visitante toque.
- Qué motor de seguimiento: solo importa en la web; las apps nativas usan siempre el de la plataforma.
Comportamiento que sobrevive a una escena
Dale a una entity comportamiento y ningún padre, y dejará de pertenecer a una escena concreta: pertenece a todo el space. Sigue corriendo mientras las escenas van y vienen, y oye cada evento que ocurra en cualquier sitio.
Ahí es donde viven un marcador de puntos, un controlador global o «recordar qué eligió el visitante». Un script dentro de una escena se para en el momento en que se para esa escena.
Cómo etiqueta el editor a los objetos
Verás etiquetas como model, primitive, text. El editor las deduce de lo que lleva el objeto, en este orden:
referencia a splat → splat
model + skinning → animated model
model → static model
video → video ← se comprueba antes que la geometría
text → text
audio → audio
light → light
geometry → primitive
cualquier otra cosa → object
Esto explica una pequeña sorpresa: un plano reproduciendo un vídeo se etiqueta como video, no como primitive. También explica por qué material y geometría solo se pueden editar en primitivas y modelos estáticos.
Siguiente: Componentes — qué controla realmente cada uno.