> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scene-editor/extender-con-codigo/script-component.md).
# Usando el Script Component
Con el nuevo Script Component, es posible crear Entities que ejecuten código personalizado desde dentro de la propia Entity.
Los Script Components permiten la ejecución del comportamiento personalizado de una Entity sin necesidad de trabajar directamente en el `index.ts` y potencialmente en otros archivos.
## Configuración del Script Component
1. Añade el Script Component a una Entity haciendo clic en el `+` botón y selecciónalo. Crea un nuevo Script haciendo clic en **+ Add New Script Module** y elige un nombre, o usa el File Path (navega o arrastra y suelta un archivo existente).
2. Haz clic en el botón CODE del componente para abrir el editor de código predeterminado. Veamos su estructura. Para más detalles sobre cómo seleccionar y gestionar tu editor predeterminado, visita [Combinar con código](/creator/content-creator-es/scene-editor/extender-con-codigo/overview.md).
## Entender la estructura del Script
Cuando se abre el Script por primera vez, contiene el siguiente código:
```ts
import { engine, Entity } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class BuildingScript {
/**
* Propiedades
* Define campos de clase que quieras reutilizar en varios métodos.
* Ejemplo de uso: this.myVariable
*/
// private myVariable: boolean = true
/**
* Constructor / Entradas
* Los parámetros declarados aquí aparecen en la UI del Script component en Creator Hub.
* Tipos compatibles: Entity, String, Number, Boolean, ActionCallback.
*
* Nota: después de editar este archivo, haz clic en el icono de actualizar en la UI del Script component
* para ver las entradas actualizadas.
*
* Los campos `src` y `entity` en el constructor son requeridos por referencias internas.
*/
constructor(
public src: string, // NO ELIMINAR
public entity: Entity, // NO ELIMINAR
// Añade tus entradas personalizadas abajo
) {}
/**
* start()
* Se llama una vez cuando se inicializa el script.
*/
start() {
// Inicialización del script
console.log("BuildingScript inicializado para la entity:", this.entity);
}
/**
* update(dt)
* Se llama en cada frame.
* @param dt - (opcional) Delta time desde el último frame (en segundos)
*/
update(dt: number) {
// Se llama en cada frame
}
}
```
La clase se compone de tres partes principales:
* El **constructor**,
* el **start()** método
* el **update()** método.
## Constructor
El constructor contiene los parámetros que quieres exponer y modificar dinámicamente desde tu escena en Creator Hub.
```ts
export class BuildingScript {
constructor(
public src: string,
public entity: Entity,
public numericVariable: number,
) {}
...
}
```
Una vez guardado el archivo, el **Refresh** botón en el Script Component actualiza todos los cambios realizados.
Una vez actualizado, el Script Component ahora muestra el `numericVariable` añadido en el código.
## Parámetros
Si diferentes Entities usan el mismo archivo en el Script component, cada una sigue teniendo parámetros independientes: si la escena tiene dos edificios, `building1` y `building2`, ambos con un Script Component apuntando al `BuildingScript.ts` archivo, cada edificio tiene su propio `numericVariable` parámetro que puede modificarse de forma independiente.
{% hint style="warning" %}
**Nota importante**: No modificar/eliminar `public src: string` y `public entity: Entity`. Puedes añadir nuevas entradas siguiendo estas.
{% endhint %}
Los tipos permitidos para los parámetros del constructor son:
* `Entity`
* `string`
* `number`
* `boolean`
* `ActionCallback`
{% hint style="info" %}
**📔 Nota**: Ambos `públicas` y `private` los parámetros del constructor se exponen a Creator Hub. La `private` palabra clave solo restringe el acceso dentro de la `BuildingScript` clase. Para más detalles, consulta la documentación oficial de TypeScript sobre\
[Propiedades de parámetros](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties).
{% endhint %}
### Acceder a los parámetros dentro del Script
Para acceder al valor de un parámetro desde tu código, usa la notación `this.definedParameter`. Por ejemplo, `this.numericVariable` ni `this.entity`.
La plantilla Script predeterminada incluye esta línea en el método start():
`console.log("BuildingScript inicializado para la entity:", this.entity);`.
Cámbiala así para registrar el valor de una variable que definiste en el constructor:
`console.log("BuildingScript inicializado con numericVariable:`, `this.numericVariable);`
Ten en cuenta que cuando cambies el valor del parámetro en la UI de Creator Hub, también deberías ver que ese valor registrado se refleja.
### Parámetros predeterminados
El constructor, de forma predeterminada, contiene un `src` y un `entity` parámetro, estos son muy útiles para el código de tu script:
* `this.entity` siempre se refiere a la Entity que contiene el `Script` component, úsalo para acceder a información sobre la Entity o añadirle components.
* `this.src` es la ruta donde se almacena el script. Esto es especialmente útil al crear Smart Items que están pensados para ser usados por otros. Usa este campo para construir la ruta a los archivos empaquetados con tu smart item, incluso si la ruta del smart item cambia o se renombra.
```ts
export class BuildingScript {
constructor(
public src: string,
public entity: Entity,
) {}
start() {
Material.setPbrMaterial(this.entity, {
texture: Material.Texture.Common({
src: this.src + '/images/myImage.png',
})
});
}
}
```
El script anterior obtiene la Entity que posee el script y le aplica una Texture. Obtiene la textura de un `.png` archivo que viene empaquetado en la carpeta del smart item, en una subcarpeta llamada `/images`. Al usar `this.src`, nos aseguramos de que la ruta del archivo siempre sea conocida, sin importar si el smart item se importa a la scene bajo `/assets/custom/itemName` ni `/assets/asset-packs/itemName`
### Tooltips en los parámetros
Añade tooltips a tus parámetros de entrada, para que los usuarios sepan para qué se usan estos campos, o qué valores se aceptan. Los usuarios verán un icono de tooltip junto a cada campo en la UI del Script component, y podrán leer texto personalizado al pasar el cursor sobre el icono.
Para añadir tooltips a tu constructor, agrega un bloque comentado justo antes del constructor y escribe una línea con `@param` más el nombre del campo, seguido de una descripción, para cada tooltip.
```ts
/**
* @param startDate - La fecha de inicio del evento en formato YYYY-MM-DD
* @param yOffset - Cuántos metros por encima del ground mostrar el item
*/
constructor(
public src: string,
public entity: Entity,
public startDate?: string,
public yOffset: number = 0.5,
) {
}
```
Es posible que debas hacer clic en el icono de actualizar de la UI del Script component para ver los cambios en tus tooltips.
## Método start() & update()
El **start()** El método contiene código que se ejecuta solo una vez, cuando se crea la Entity (en este caso, cuando la scene carga por primera vez).
Previsualiza la scene y revisa los logs (**Consejo**: puedes usar el `` ` `` atajo): muestra el nuevo mensaje incluyendo el `numericVariable` parámetro.
El **update()** El método, por otro lado, ejecuta su código en cada frame del juego (igual que los Systems). Por ejemplo, comprobando valores de la `PlayerEntity` para activar comportamientos en el script.
El siguiente código imprime Logs en cada frame del juego si la `PlayerEntity` es mayor que la previamente definida `numericVariable`, que el creador proporciona dinámicamente desde la UI del Script Component.
```ts
update(dt: number) {
if (Transform.get(engine.PlayerEntity).position.y > this.numericVariable ) {
console.log("La altura del jugador supera ", this.numericVariable);
}}
```
El primer log pertenece al método start(), indicando que establecemos numericVariable. El segundo pertenece al método update(), cuando el jugador está por encima de ese valor.
## Exponer Actions a Creator Hub
Es posible definir una `Action` dentro de un script de Script Component y que sea accesible en la UI de Creator Hub. Esto habilita la posibilidad de activar esta `Action` con otra Entity.
```ts
/**
* Expone esta acción para que pueda activarse
* @action
*/
exposedAction(creatorHubParameter: number) {
console.log("Activado desde otra entity usando el parámetro: ", this.creatorHubParameter);
}
```
`creatorHubParameter` se expondrá como un `Action` parámetro para darle un valor personalizado. Después de actualizar el Script Component, la nueva action estará disponible como opción en el desplegable de Actions.
Después de añadir la Action, cualquier Entity en Creator Hub puede activarla usando `Triggers`
{% hint style="info" %}
**📔 Nota**: Puedes añadir tantas Actions como necesites dentro del Script. Todas ellas serán accesibles de forma independiente desde el `Action` desplegable.
{% endhint %}
## Llamar métodos de Script desde fuera
Para llamar a un método de Script desde otro Script o desde `src/index.ts`, deben seguirse los siguientes pasos:
1. Crea un `públicas` método dentro de la clase Script.
2. Ejecuta `npm run build` desde el directorio raíz de la scene.
3. Desde el archivo donde quieras usar el método público, añade `import { callScriptMethod } from '~sdk/script-utils'`.
4. Llama a `callScriptMethod` con los parámetros necesarios (en este caso, `someParamter`).
Aquí tienes un ejemplo con un `públicas` método expuesto
```ts
export class BuildingScript {
constructor(
public src: string,
public entity: Entity,
...,
) {}
public publicMethod(boolParameter: boolean, someNumberParameter: number) {
if (boolParameter) {
console.log("¡Método público llamado con el parámetro true!: ", someNumberParameter);
} else {
console.log("¡Método público llamado con el parámetro false!", someNumberParameter);
}
}
...
}
```
Para llamarlo desde `src/index.ts`, usa:
```ts
import { callScriptMethod } from '~sdk/script-utils'
export function main() {
const buildingEntity = engine.getEntityOrNullByName("building")
if (buildingEntity) {
const scriptMethod = callScriptMethod(
buildingEntity,
"assets/scene/Scripts/BuildingScript.tsx",
"publicMethod",
false,
3,
)
scriptMethod
}
}
```
Primero, la `main` función busca la `Entity` que tiene el Script component. Segundo, si la `Entity` existe, `callScriptMethod` se llama con los siguientes parámetros:
1. `entity`: `Entity` que tiene el `públicas` método.
2. `scriptPath`: `ruta` donde vive la `Script` clase.
3. `methodName`: nombre del `públicas` método que se llamará.
4. `...args`: Argumentos del método. En este caso, hay dos. Deben añadirse en orden, uno tras otro.
Tercero, llamamos al `callScriptMethod`, en este caso, `scriptMethod`.
Con los valores de los parámetros dados, la salida es:
{% hint style="info" %}
**📔 Nota**: Puedes seguir la misma lógica para llamar a un `públicas` método de Script desde otro script o archivo. Puedes usarlo para obtener o cambiar valores de `públicas` variables en la clase Script.
{% endhint %}
## Activar las Actions de otras Entities desde un Script
Es posible usar un parámetro de tipo `ActionCallback` en el constructor de la clase Script. Esto permite activar la `Entity`de `Action` definida a través de la UI de Creator Hub desde los métodos del Script.
En este ejemplo, `anotherEntityAction` se añade como una `públicas` parámetro.
```ts
export class BuildingScript {
constructor(
public src: string,
public entity: Entity,
public anotherEntityAction: ActionCallback,
...,
) {}
...
}
```
Una acción seleccionable `Entity` y `Action` ya están disponibles cuando el Script Component se actualiza en la UI de Creator Hub. `Sphere` es una Entity ya existente en la escena que tiene una action llamada `Scale`.
La acción de la otra Entity ahora es accesible en la clase Script. Puede usarse de muchas maneras diferentes. En el siguiente ejemplo, al presionar E se activará `this.anotherEntityAction` definiendo un `pointerEventsSystem` en el `start` método.
```ts
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: {
button: InputAction.IA_PRIMARY,
hoverText: "Presiona E para activar una Action de otra Entity.",
},
},
() => {
this.anotherEntityAction();
}
);
}
```
{% hint style="info" %}
**📔 Nota**: Combinar exponer y activar `Actions` es una herramienta muy poderosa. Puedes definir un Script Component en una Entity, exponer una acción usando un `públicas` método, y luego activarla desde el Script Component de otra Entity usando un `ActionCallback` parámetro.
{% endhint %}
## Ver también
* [Smart items - Basics](/creator/content-creator-es/scene-editor/interactividad/smart-items.md)
* [Smart items - Advanced](/creator/content-creator-es/scene-editor/interactividad/smart-items-advanced.md)
* [States and conditions](/creator/content-creator-es/scene-editor/interactividad/states-and-conditions.md)
* [Hacer smart cualquier item](/creator/content-creator-es/scene-editor/interactividad/make-any-item-smart.md)
* [Inicio rápido del SDK](/creator/content-creator-es/escenas-sdk7/primeros-pasos/sdk-101.md): sigue este mini tutorial para obtener una introducción rápida.
* [Flujo de trabajo de desarrollo](/creator/content-creator-es/escenas-sdk7/primeros-pasos/dev-workflow.md): léelo para entender la creación de scenes de principio a fin.
* [Ejemplos](https://studios.decentraland.org/resources?sdk_version=SDK7): sumérgete directamente en scenes de ejemplo que funcionan.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.decentraland.org/creator/content-creator-es/scene-editor/extender-con-codigo/script-component.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.