Instancias del motor | Documentación del Centro de creación de Roblox

Las API de Open Cloud del Motor te permiten gestionar objetos Instance en tus juegos de Roblox desde la web.

Restricciones beta

Estas API están actualmente en beta y tienen las siguientes restricciones:

Solo puedes leer y actualizar objetos Script, LocalScript y ModuleScript.
No puedes actualizar scripts que estén actualmente abiertos en Roblox Studio.
No puedes actualizar scripts que sean parte de un paquete.
Solo puedes usar autenticación de clave API. Crea una clave API con universe-place-instances añadida como un sistema API.

Debes especificar los juegos a los que quieres que la clave tenga acceso, así como los ámbitos deseados de permisos de lectura y escritura.
Debes tener una sesión de colaboración habilitada para el juego al que deseas acceder.
Los cuerpos de las solicitudes, como al Actualizar Instancia, están limitados a 200 KB.

Listar hijos

Lista todos los hijos de una instancia específica especificando una ID de instancia y llamando al método Listar Hijos de la Instancia.

La primera vez que uses estos métodos, especifica root como la ID de la instancia. Después de recibir la lista de los hijos de nivel superior y sus ID, puedes hacer llamadas adicionales para encontrar instancias más profundas dentro de la jerarquía de instancias de tu lugar.


import requests

# Generado en https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encuentra en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
universeId = "<UNIVERSE_ID>"
# Encuentra la ID del Lugar Inicial en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
placeId = "<PLACE_ID>"
# La ID predeterminada para la raíz de cualquier modelo de datos de un lugar
instanceId = "root"

# Encabezado de solicitud
apiKeyHeaderKey = "x-api-key"
# URL del punto final para el método Listar Hijos
listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

response = ListChildren()
print("Resultados de la operación:", response.status_code, response.text)

# Analiza la ruta del objeto de operación para obtener más tarde el recurso de la Instancia. Consulta la sección de Polling for Results para más información.
operationPath = response.json()['path']

En lugar de solo listar los hijos, la respuesta incluye un objeto Operation con un punto final diferente. Poll this endpoint para recuperar de forma asincrónica la lista real de hijos. Un ejemplo de código más completo se ve así:


import requests
import time

apiKey = "<API_KEY>"
universeId = "<UNIVERSE_ID>"
placeId = "<PLACE_ID>"
instanceId = "root"

apiKeyHeaderKey = "x-api-key"

listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"

numberOfRetries = 10
retryPollingCadence = 5

doneJSONKey = "done"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = ListChildren()
print("Resultados de la operación:", response.status_code, response.text)
# Analiza la ruta del objeto de operación para usar en la polling del recurso de instancia.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Respuesta:", response.status_code, response.text)

La respuesta final podría verse algo así:


{
  "path": "universes/1234567890/places/98765432109/instances/root/operations/a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/roblox.open_cloud.cloud.v2.ListInstanceChildrenResponse",
    "instances": [
      {
        "path": "universes/1234567890/places/98765432109/instances/b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
        "hasChildren": true,
        "engineInstance": {
          "Id": "b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
          "Parent": "a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
          "Name": "Workspace",
          "Details": {}
        }
      },

      ...

    ]
  }
}

Luego puedes iterar sobre el JSON para encontrar una ID de instancia particular:


instances = response.json()['response']['instances']
replicatedStorageId = ""
for i in instances:
  if i['engineInstance']['Name'] == "ReplicatedStorage":
    replicatedStorageId = i['engineInstance']['Id']

if replicatedStorageId:
  # Ahora tienes una ID de instancia y puedes obtenerla o actualizarla.
else:
  # El nombre no fue encontrado.

Los scripts contienen información adicional en el objeto Details, como el tipo de script, la fuente y si están habilitados.

Obtener una instancia

Este método devuelve una sola Instancia.


import requests

# Generado en https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encuentra en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
universeId = "<UNIVERSE_ID>"
# Encuentra la ID del Lugar Inicial en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
placeId = "<PLACE_ID>"
# La ID predeterminada para la raíz de cualquier modelo de datos de un lugar
instanceId = "<INSTANCE_ID>"

# Encabezado de solicitud
apiKeyHeaderKey = "x-api-key"
# URL del punto final para el método Obtener Instancia
getInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"

def GetInstance():
  url = getInstanceUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  return requests.get(url, headers = headerData)

response = GetInstance()
print("Respuesta:", response.status_code, response.text)

# Analiza la ruta del objeto de operación desde la respuesta. Consulta la sección de Polling for Results para más información.
operationPath = response.json()['path']

Al igual que el método Listar Hijos de la Instancia, la respuesta incluye un objeto Operation que debes consultar para recuperar la instancia real. Consulta Poll for results para más información.

Actualizar instancias

Después de obtener la ID de instancia adecuada, puedes actualizarla. Poll for results después de hacer la solicitud inicial de actualización.


import json
import requests

# Generado en https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Encuentra en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
universeId = "<UNIVERSE_ID>"
# Encuentra la ID del Lugar Inicial en https://create.roblox.com/dashboard/creations en el menú desplegable de un tile de juego
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Encabezado de solicitud
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL del punto final para el método Actualizar Instancia
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Claves JSON
detailsJSONKey = "Details"
engineInstanceJSONKey = "engineInstance"

def GeneratePostData():
  propertiesDict = {propertyName: propertyValue}
  detailsDict = {instanceType: propertiesDict}
  instanceDict = {detailsJSONKey: detailsDict}
  outerDict = {engineInstanceJSONKey: instanceDict}
  return json.dumps(outerDict)

def UpdateInstance(postData):
    url = updateInstanceUrl % (universeId, placeId, instanceId)
    headerData = {apiKeyHeaderKey: apiKey,
    contentTypeHeaderKey: contentTypeHeaderValue}
    return requests.patch(url, headers = headerData, data = postData)

postData = GeneratePostData()
response = UpdateInstance(postData)
print("Respuesta:", response.status_code, response.text)

# Analiza la ruta del objeto de operación desde la respuesta. Realiza la consulta para obtener resultados
# de la actualización.
operationPath = response.json()['path']

Si recibes un TypeError al intentar actualizar un script, verifica que el script no esté abierto en Roblox Studio. Si lo está, cierra su pestaña del Editor de Scripts. También puedes comprobar la salida del Studio en busca de errores adicionales, como Engine_OC_API: Processing Error - Live scripting session is active.

Poll for results

Todos los métodos actuales de Instancia devuelven un objeto Operation en lugar del recurso que solicitaste. Este objeto te permite realizar de forma asincrónica la operación original. Usa la ruta del objeto Operation (incluida en la respuesta inicial) para consultar cuándo el recurso está listo.

Puedes usar una variedad de estrategias de consulta, como utilizar retrocesos exponenciales o un retraso fijo entre solicitudes. El siguiente ejemplo consulta cada cinco segundos, hasta 10 veces.


import requests
import time

# Generado en https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Usa la ruta de la operación de tu solicitud inicial
# Toma la forma de "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Constantes de consulta
numberOfRetries = 10
retryPollingCadence = 5

# Encabezado de solicitud
apiKeyHeaderKey = "x-api-key"
# URL del punto final para la consulta de operaciones de larga duración
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Claves JSON
doneJSONKey = "done"

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = PollForResults(operationPath)
print("Respuesta:", response.status_code, response.text)

Demo de la tienda de pociones

La demo de Google Sheets de la tienda de pociones te muestra cómo actualizar el script de un juego desde la web. La demo consiste en lo siguiente:

Un lugar sin copia bloqueada con una interfaz de usuario simulada que muestra varias pociones y sus precios.
Un archivo .ods que importas en Google Sheets. Esta hoja de cálculo te permite especificar y actualizar valores para propiedades dentro del juego.
Código para un Google Apps Script que lee datos de la hoja de Google y actualiza el script ReplicatedStorage > ItemList en el juego de la tienda de pociones.

Configura la demo

Ve a la página de Descubrimiento de la Demo de la tienda de pociones. Haz clic en el menú desplegable y luego en Editar en Studio. Studio se abre con una copia del lugar.
Haz clic en Archivo → Guardar en Roblox y completa la información necesaria para guardar la Demo de la tienda de pociones como el lugar predeterminado para tu juego. Prueba el juego. Deberías ver la interfaz de usuario de la Demo de la tienda de pociones. Toma nota del nombre, costo y colores de las pociones. ¡Los cambiarás más tarde usando Open Cloud!

Configura la hoja

Descarga el archivo de la hoja de cálculo de la tienda de pociones.
Ve a Google Sheets y haz clic en Hoja de Cálculo en Blanco.
En la hoja que aparece, haz clic en Archivo > Importar y haz clic en la pestaña Cargar.
Arrastra el archivo de la hoja de cálculo de la tienda de pociones a la ventana de carga.
Elige Reemplazar hoja de cálculo y luego Importar datos.
En la pestaña AppScript de la hoja, copia el código de la celda A1.
Haz clic en el menú Extensiones > Apps Script y pega el código en el archivo Code.gs. Luego guarda el proyecto.
De vuelta en la hoja de cálculo, selecciona la pestaña Actualizar tienda de pociones. Haz clic en el botón Actualizar Script, haz clic en el menú desplegable y selecciona Asignar script.
En la ventana Asignar script, ingresa UpdateScript y haz clic en OK.

Crea una clave API

Ve a la página de Claves API de Open Cloud del Creator Hub y haz clic en Crear clave API.
Completa el formulario con la siguiente información.
- Nombre: PotionShop
- Sistema API: Añade el sistema API universe-place-instances. Agrega tu juego de la tienda de pociones al sistema. Para Operaciones de Experiencia, añade acceso de lectura y escritura.
- Direcciones IP aceptadas: Añade 0.0.0.0/0 como Dirección IP
- Expiración: Sin expiración
- Haz clic en Guardar y generar clave y luego en Copiar clave al portapapeles.
Pega la clave API en la celda de clave API (D2) en la pestaña Intro de tu hoja de Google.

Obtén la ID de universo y lugar

Ve a la página de Creaciones del Creator Hub, pasa el ratón sobre el tile del juego de la tienda de pociones y haz clic en el menú desplegable.
Selecciona Copiar ID de Universo y pégalo en la celda ID de Universo (E2) en la pestaña Intro de tu hoja de Google.
Selecciona Copiar ID de Lugar Inicial y pégalo en la celda ID de Lugar (F2) en la pestaña Intro de tu hoja de Google.

Actualiza los valores del script

En la pestaña Actualizar tienda de pociones de la hoja, modifica cualquier valor que desees y haz clic en el botón Actualizar Script.
Si Google Sheets te solicita autorización, haz clic en OK y permite que tu cuenta ejecute el script.
En Studio, prueba el juego de la tienda de pociones para ver cualquier cambio reflejado. Desde la ventana Explorer, también puedes abrir el script ReplicatedStorage > ItemList para inspeccionar los cambios.