habilidad-offline-roblox

Habilidad Offline de Roblox

Propósito

Usa esta habilidad para construir y revisar sistemas confiables de datos de jugadores y progresión calculada para el tiempo fuera del juego. Abarca arquitectura, implementación, pruebas, operaciones y recuperación. Es una guía para un agente de IA, no un marco de persistencia desplegable.

Condiciones de activación

Usa esta habilidad cuando una tarea involucre:

• Guardar, cargar, restablecer, migrar, restaurar o inspeccionar datos de jugadores.
• DataStoreService, DataStores estándar, OrderedDataStores, MemoryStoreService, Open Cloud DataStores o el Administrador de Data Stores de Creator Hub.
• Perfiles de jugador, monedas, inventario, mascotas, mejoras, terrenos, cultivos, máquinas, generadores, tablas de clasificación y configuraciones persistentes.
• Propiedad de sesión, bloqueo de sesión, guardado automático, reintentos, presupuestos de solicitudes, limitación, PlayerRemoving o BindToClose.
• Ganancias offline, ingresos inactivos, temporizadores de cultivo, producción, tiempos de espera o progreso después de reconectar.
• Pérdida de datos, escrituras obsoletas, recompensas duplicadas, registros corruptos, recibos de compra o migraciones de esquema.

No uses esta habilidad para tareas no relacionadas de UI, mapa, animación, combate o jugabilidad general a menos que toquen datos persistentes de jugadores.

Hechos fundamentales

1. DataStoreService proporciona almacenamiento persistente en la nube de Roblox. Se accede mediante código del servidor y requiere conectividad con los servicios de Roblox.
2. El Administrador de Data Stores de Creator Hub es un panel para ver y gestionar datos. No es un servicio Luau ni una API de base de datos en tiempo de ejecución.
3. MemoryStoreService proporciona datos temporales entre servidores. Las entradas caducan y no es un almacén de perfiles de jugador permanente.
4. OrderedDataStore es para valores numéricos ordenados, comúnmente puntuaciones persistentes de tablas de clasificación. No es un perfil de jugador completo.
5. La memoria del servidor es la copia de trabajo volátil del servidor activo. Puede perderse si el proceso finaliza antes de un guardado exitoso.
6. La progresión offline normalmente significa una recuperación acotada calculada por el servidor después de que un jugador regresa. No significa que un mundo privado continúe simulando sin un servidor activo.
7. Un cliente completamente desconectado no puede escribir en DataStores en la nube de Roblox. No prometas que una experiencia Roblox publicada normal pueda seguir jugando y guardando en la nube sin conectividad.
8. Las llamadas a DataStoreService pertenecen a Scripts del servidor o ModuleScripts requeridos por Scripts del servidor. Nunca guardes datos canónicos desde un LocalScript.
9. UpdateAsync es una operación de lectura-modificación-escritura. Por sí sola, no implementa el bloqueo de sesión.
10. Una solicitud exitosa no prueba que el perfil devuelto sea estructuralmente válido o compatible con el esquema actual.
11. Una carga fallida no equivale a una clave faltante o un nuevo jugador.
12. Nunca claims que el código fue probado en Roblox Studio a menos que la experiencia objetivo se haya ejecutado realmente en Studio.

Flujo de trabajo requerido

1. Inspeccionar antes de editar

Inspecciona la experiencia real, archivos, scripts, ModuleScripts, remotos, paquetes e integraciones de Studio disponibles.

Identifica:

• Cada nombre de DataStore, alcance, constructor de claves, prefijo de clave y adaptador de almacenamiento.
• Todas las llamadas GetAsync, SetAsync, UpdateAsync, IncrementAsync, versión y listado.
• PlayerAdded, PlayerRemoving, BindToClose, tareas de guardado automático, manejadores de recibos de compra y cada escritor para cada clave de perfil.
• El esquema actual, plantilla predeterminada, versión de migración y el punto exacto donde un perfil se vuelve escribible.
• Si el proyecto usa DataStoreService nativo, una biblioteca de perfiles de terceros o un envoltorio personalizado.
• Cómo se manejan actualmente la propiedad del perfil, reintentos, ordenación de misma clave y apagado.
• Qué significa el usuario por offline: recuperación por tiempo fuera, interrupción temporal del servicio, pruebas simuladas o juego completamente desconectado.

No infieras la arquitectura a partir de una captura de pantalla, un nombre de repositorio o algunos fragmentos de código aislados. Preserva un sistema funcional a menos que la evidencia muestre una razón concreta para cambiarlo.

2. Verificar el comportamiento de Roblox

Usa references/official-roblox-sources.md como índice de fuentes. Vuelve a consultar la documentación actual de Roblox Creator Hub para firmas de API, cuotas, comportamiento del servicio, configuración y deprecaciones antes de codificar.

Usa la documentación de Roblox para garantías del motor. Para paquetes de terceros, inspecciona la versión exacta instalada en el proyecto objetivo y verifica la API de ese paquete. No inventes métodos de bibliotecas de memoria o ejemplos antiguos.

3. Elegir almacenamiento según los requisitos

Requisito	Punto de partida correcto
Progreso duradero del jugador	DataStore estándar a través de DataStoreService o una capa de perfil mantenida
Clasificación numérica persistente	OrderedDataStore
Estado compartido temporal entre servidores	MemoryStoreService
Perfil vivo del servidor actual	Memoria del servidor
Inspeccionar o recuperar entradas almacenadas	Administrador de Data Stores de Creator Hub y APIs de versión
Administración externa	Open Cloud a través de un backend confiable
Progreso por tiempo fuera	Perfil persistente más cálculo de recuperación del lado del servidor
Juego independiente completamente desconectado	No proporcionado por DataStores normales de Roblox

Prefiere una clave de perfil estable basada en UserId cuando el perfil quepa y sus campos necesiten actualizaciones coherentes. Divide solo por una razón real de tamaño, rendimiento o patrón de acceso. No crees un DataStore por jugador.

4. Cargar y poseer perfiles de forma segura

Un perfil se vuelve escribible solo después de una carga exitosa y propiedad exclusiva bajo la arquitectura seleccionada.

1. Comienza a cargar cuando el servidor reciba PlayerAdded.
2. Adquiere el bloqueo de perfil/sesión usando la capa de persistencia existente.
3. Distingue un resultado de clave faltante válido de fallo de red, limitación, conflicto de sesión, datos malformados y esquema no compatible.
4. Valida la carga útil y aplica migraciones ordenadas y deterministas.
5. Publica el perfil como listo solo después de que todos los pasos requeridos tengan éxito.
6. Permite que la jugabilidad del servidor modifique la copia de trabajo de propiedad del servidor a través de métodos controlados.
7. Detén las mutaciones inmediatamente si la biblioteca de perfiles informa que la propiedad terminó.

Nunca crees un perfil predeterminado escribible después de un fallo de carga transitorio. Eso podría sobrescribir los datos reales de un jugador que regresa.

5. Guardar con orden y reintentos acotados

• Maneja las llamadas de red con pcall o la capa de errores establecida del proyecto.
• Reintenta solo errores transitorios, usando retroceso exponencial acotado y jitter aleatorio.
• No reintentes argumentos inválidos o fallos permanentes para siempre.
• Serializa las escrituras por clave. Un reintento retrasado antiguo no debe sobrescribir un guardado exitoso más reciente.
• Diseña operaciones reintentables para que sean idempotentes porque una respuesta fallida puede dejar el resultado de la escritura incierto.
• Usa UpdateAsync cuando el nuevo valor dependa del estado almacenado actual o puedan ocurrir escrituras concurrentes.
• SetAsync es válido para reemplazo intencional de valor completo cuando se establecen propiedad exclusiva y semánticas de reemplazo. No lo llames universalmente prohibido.
• Mantén las devoluciones de llamada de transformación de UpdateAsync deterministas, sin rendimiento y libres de efectos secundarios externos. Nunca realices esperas, llamadas HTTP, llamadas remotas, concesiones de recibos, análisis o creación de Instancias dentro de la devolución de llamada.
• Un retorno nil de una transformación de UpdateAsync cancela la escritura.
• Observa los presupuestos de solicitudes actuales y el comportamiento de limitación. UpdateAsync consume presupuesto tanto de lectura como de escritura.
• Escalon los guardados automáticos. No guardes cada fotograma o para cada evento de jugabilidad pequeño.

6. Implementar la progresión offline correctamente

Lee references/offline-progression.md y examples/offline-progress.luau antes de construir un sistema de recompensas offline.

El servidor debe:

1. Cargar y validar el perfil.
2. Confirmar la propiedad exclusiva de la sesión.
3. Leer las marcas de tiempo guardadas y las entradas de producción propiedad del servidor.
4. Obtener la hora de época del lado del servidor actual.
5. Calcular el tiempo transcurrido no negativo y limitarlo a un máximo configurado.
6. Derivar las tasas de producción de la propiedad validada y las definiciones del lado del servidor.
7. Aplicar la eficiencia offline configurada, elegibilidad y límites de recompensa.
8. Actualizar la recompensa y su marca de tiempo de simulación correspondiente juntos en la copia de trabajo del perfil.
9. Persistir a través de la capa de perfil activa.
10. Replicar los datos de presentación al cliente.

Usa os.time() u otra marca de tiempo de época del lado del servidor documentada para cálculos entre sesiones. Nunca uses os.clock() como marca de tiempo de época. Nunca confíes en el reloj del cliente, la duración transcurrida, la tasa de producción, la etapa del cultivo, la lista de activos o la marca de tiempo del último reclamo.

No recompenses el mismo intervalo dos veces. No dupliques la producción en línea. No ejecutes un bucle ilimitado por cada segundo offline. Maneja marcas de tiempo faltantes, malformadas, cero, negativas y futuras deliberadamente.

7. Proteger los datos de desarrollo y producción

• Usa una experiencia de desarrollo o staging publicada separada para pruebas de integración de DataStore en vivo.
• Habilita el Acceso a API de Studio solo en esa experiencia de prueba aislada.
• Roblox advierte que Studio puede acceder a los mismos DataStores que la aplicación en vivo. Nunca habilites esta configuración en producción para pruebas rutinarias.
• Usa simulaciones (mocks) o un adaptador en memoria para pruebas de lógica deterministas. Una simulación no es un guardado de jugador real ni almacenamiento duradero.
• Usa cuentas desechables y claves de prueba.
• No elimines, reviertas, renombres o sobrescribas datos de producción sin autorización explícita del operador, identificación exacta del objetivo y un plan de recuperación.
• Mantén las credenciales de Open Cloud en un backend confiable. Nunca las expongas en un LocalScript, cliente, repositorio público o contexto de indicaciones.

8. Verificar e informar honestamente

Usa references/test-matrix.md. Cubre perfiles por primera vez y de regreso, fallos de carga, conflictos, propietarios obsoletos, orden de escritura, reintentos, guardado automático, apagado, recuperación de fallos, cargas útiles malformadas, migraciones, límites offline, reclamos repetidos y recibos duplicados.

Informa el nivel de validación con precisión:

• Revisión estática
• Pruebas unitarias puras
• Pruebas de integración simuladas/en memoria
• Pruebas de DataStore de staging publicadas
• Pruebas de tiempo de ejecución de Roblox Studio
• Pruebas de conflicto multi-servidor/sesión

Estas son verificaciones diferentes. Si Studio o staging no estuvo disponible, indica que la validación en tiempo de ejecución sigue pendiente.

Prohibiciones no negociables

• Nunca guardes datos canónicos de jugador desde un LocalScript.
• Nunca confíes en UserIds, saldos, precios, inventario, propiedad, tasas de recompensa, marcas de tiempo, tiempo transcurrido o resultados de compra proporcionados por el cliente.
• Nunca trates un error de carga transitorio como un nuevo jugador.
• Nunca uses MemoryStoreService o RAM del servidor como almacenamiento de perfiles permanente.
• Nunca uses DataStore2 para una nueva experiencia. Roblox lo identifica actualmente como una biblioteca heredada.
• Nunca cedas o realices efectos secundarios en devoluciones de llamada de UpdateAsync.
• Nunca permitas que escrituras de la misma clave y reintentos compitan.
• Nunca robes por la fuerza una sesión activa como un reintento normal.
• Nunca escribas valores sin procesar sobre una clave gestionada por una biblioteca de perfiles.
• Nunca claims que UpdateAsync por sí solo implementa un bloqueo de sesión.
• Nunca ejecutes bucles de simulación offline ilimitados.
• Nunca expongas secretos de Open Cloud.
• Nunca modifiques datos de producción de manera destructiva sin autorización explícita y un plan de recuperación.
• Nunca claims pruebas de Studio que no ocurrieron.

Mapa de referencia

Carga solo los documentos necesarios para la tarea actual:

• references/architecture-and-services.md: roles de servicio, Administrador de Data Stores, Open Cloud y selección de almacenamiento.
• references/player-data-lifecycle.md: ciclo de vida del perfil, copias de trabajo en memoria, preparación, salida y apagado.
• references/session-locking-and-failures.md: propiedad de sesión, UpdateAsync, orden de escritura, reintentos, limitación y resultados desconocidos.
• references/offline-progression.md: recompensas inactivas, temporizadores de cultivo, generadores, matemáticas de marcas de tiempo, límites y limitaciones desconectadas.
• references/studio-testing.md: acceso a API, staging, simulaciones y aislamiento seguro de pruebas.
• references/schema-migrations-and-recovery.md: serialización, versiones de esquema, migraciones, historial de versiones y recuperación.
• references/security-and-purchases.md: remotos, autoridad del servidor, recibos, secretos de Open Cloud y privacidad de datos.
• references/performance-and-limits.md: límites documentados, presupuestos, rendimiento y ajuste operativo.
• references/library-selection.md: DataStoreService nativo, código de referencia oficial y evaluación de paquetes de terceros.
• references/game-patterns.md: perfiles, tablas de clasificación, terrenos, sistemas inactivos, comercio y compras.
• references/test-matrix.md: escenarios de verificación.
• references/official-roblox-sources.md: solo enlaces a fuentes de Roblox Creator Hub.
• examples/profile-template.luau: forma ilustrativa de perfil.
• examples/offline-progress.luau: cálculo de recompensa offline acotado puro.

Respuesta de implementación requerida

Para tareas de implementación y depuración:

1. Resume la arquitectura existente encontrada en el proyecto real.
2. Explica el flujo de datos previsto y el cambio más pequeño seguro.
3. Enumera los archivos exactos a crear o modificar.
4. Entrega código completo y consciente del contexto, no fragmentos desconectados.
5. Explica los pasos de configuración, staging y cualquier migración de esquema.
6. Informa las pruebas reales y las comprobaciones de tiempo de ejecución restantes.
7. Indica los límites y riesgos materiales sin inventar garantías.

Respeta el idioma y estilo solicitados por el usuario. Preserva los sistemas funcionales. No agregues características no relacionadas ni reemplaces una biblioteca de persistencia existente por razones estilísticas.