Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

JSON

Hereda: Resource < RefCounted < Object

Clase auxiliar para crear y analizar datos JSON.

Descripción

La clase JSON permite que todos los tipos de datos se conviertan a y desde una string JSON. Esto es útil para serializar datos, por ejemplo, para guardar en un archivo o enviar a través de la red.

stringify() se usa para convertir cualquier tipo de dato en una string JSON.

parse() se usa para convertir cualquier dato JSON existente en un Variant que se pueda usar dentro de Godot. Si se parsea con éxito, usa data para recuperar el Variant, y usa @GlobalScope.typeof() para comprobar si el tipo del Variant es el que esperas. Los objetos JSON se convierten en un Dictionary, pero los datos JSON se pueden usar para almacenar Arrays, números, Strings e incluso simplemente un booleano.

var data_to_send = ["a", "b", "c"]
var json_string = JSON.stringify(data_to_send)
# Guardar datos
# ...
# Recuperar datos
var json = JSON.new()
var error = json.parse(json_string)
if error == OK:
    var data_received = json.data
    if typeof(data_received) == TYPE_ARRAY:
        print(data_received) # Imprime el array.
    else:
        print("Datos inesperados")
else:
    print("Error de análisis JSON: ", json.get_error_message(), " en ", json_string, " en la línea ", json.get_error_line())

Alternativamente, puedes parsear cadenas usando el método estático parse_string(), pero no maneja errores.

var data = JSON.parse_string(json_string) # Devuelve null si el análisis falló.

Nota: Ambos métodos de análisis no cumplen completamente con la especificación JSON:

Las comas finales en arrays u objetos se ignoran, en lugar de causar un error de análisis.
Se aceptan caracteres de nueva línea y tabulación en literales de string, y se tratan como sus secuencias de escape correspondientes \n y \t.
Los números se parsean usando String.to_float(), que es generalmente más laxo que la especificación JSON.
Ciertos errores, como secuencias Unicode inválidas, no causan un error de análisis. En su lugar, la string se limpia y se registra un error en la consola.

Propiedades

Variant

data

null

Métodos

Variant	from_native(variant: Variant, full_objects: bool = false) static
int	get_error_line() const
String	get_error_message() const
String	get_parsed_text() const
Error	parse(json_text: String, keep_text: bool = false)
Variant	parse_string(json_string: String) static
String	stringify(data: Variant, indent: String = "", sort_keys: bool = true, full_precision: bool = false) static
Variant	to_native(json: Variant, allow_objects: bool = false) static

Descripciones de Propiedades

Variant data = null 🔗

void set_data(value: Variant)
Variant get_data()

Contiene los datos JSON analizados en formato Variant.

Descripciones de Métodos

Variant from_native(variant: Variant, full_objects: bool = false) static 🔗

Convierte un tipo de motor nativo en un valor compatible con JSON.

Por defecto, los objetos se ignoran por razones de seguridad, a menos que full_objects sea true.

Puedes convertir un valor nativo en una cadena JSON de esta manera:

func encode_data(value, full_objects = false):
    return JSON.stringify(JSON.from_native(value, full_objects))

int get_error_line() const 🔗

Devuelve 0 si la última llamada a parse() fue exitosa, o el número de línea donde falló el análisis.

String get_error_message() const 🔗

Devuelve una string vacía si la última llamada a parse() fue exitosa, o el mensaje de error si falló.

String get_parsed_text() const 🔗

Devuelve el texto analizado por parse() (requiere pasar keep_text a parse()).

Error parse(json_text: String, keep_text: bool = false) 🔗

Intenta analizar el json_text proporcionado.

Devuelve un Error. Si el análisis fue exitoso, devuelve @GlobalScope.OK y el resultado se puede recuperar usando data. Si no tiene éxito, usa get_error_line() y get_error_message() para identificar la causa del fallo.

Variante no estática de parse_string(), si quieres un manejo de errores personalizado.

El argumento opcional keep_text instruye al analizador a mantener una copia del texto original. Este texto se puede obtener más tarde usando la función get_parsed_text() y se usa al guardar el recurso (en lugar de generar nuevo texto a partir de data).

Variant parse_string(json_string: String) static 🔗

Intenta analizar la json_string proporcionada y devuelve los datos analizados. Devuelve null si el análisis falla.

String stringify(data: Variant, indent: String = "", sort_keys: bool = true, full_precision: bool = false) static 🔗

Convierte una variable Variant a texto JSON y devuelve el resultado. Útil para serializar datos para almacenar o enviar a través de la red.

Nota: La especificación JSON no define tipos enteros o floats, sino solo un tipo número. Por lo tanto, convertir una Variant a texto JSON convertirá todos los valores numéricos a tipos float.

Nota: Si full_precision es true, al convertir floats a string, los dígitos no fiables se convierten a string además de los dígitos fiables para garantizar una decodificación exacta.

El parámetro indent controla si y cómo se indenta algo; su contenido se utilizará donde deba haber una indentación en la salida. Incluso espacios como " " funcionarán. \t y \n también pueden usarse para una indentación de tabulación, o para hacer un salto de línea para cada indentación respectivamente.

Advertencia: Los números no finitos no son compatibles con JSON. Cualquier ocurrencia de @GDScript.INF será reemplazada por 1e99999, y @GDScript.INF negativo será reemplazado por -1e99999, pero la mayoría de los analizadores JSON los interpretarán correctamente como infinito. @GDScript.NAN será reemplazado por null, y no se interpretará como NaN en los analizadores JSON. Si esperas números no finitos, considera pasar tus datos por from_native() primero.

Ejemplo de salida:

## JSON.stringify(my_dictionary)
{"name":"my_dictionary","version":"1.0.0","entities":[{"name":"entity_0","value":"value_0"},{"name":"entity_1","value":"value_1"}]}

## JSON.stringify(my_dictionary, "\t")
{
    "name": "my_dictionary",
    "version": "1.0.0",
    "entities": [
        {
            "name": "entity_0",
            "value": "value_0"
        },
        {
            "name": "entity_1",
            "value": "value_1"
        }
    ]
}

## JSON.stringify(my_dictionary, "...")
{
..."name": "my_dictionary",
..."version": "1.0.0",
..."entities": [
......{
........."name": "entity_0",
........."value": "value_0"
......},
......{
........."name": "entity_1",
........."value": "value_1"
......}
...]
}

Variant to_native(json: Variant, allow_objects: bool = false) static 🔗

Convierte un valor compatible con JSON que se creó con from_native() de nuevo a los tipos de motor nativos.

Por defecto, los objetos se ignoran por razones de seguridad, a menos que allow_objects sea true.

Puedes convertir un string JSON de nuevo a un valor nativo así:

func decode_data(string, allow_objects = false):
    return JSON.to_native(JSON.parse_string(string), allow_objects)