Godot Mastery: Automating GDScript Data Structures

JSON to Godot GDScript: Parsing API Data into Typed Classes

Godot 4's GDScript has static typing and a class system that makes working with external JSON data much cleaner than the old dictionary-everywhere approach. When your game fetches player data, level configs, or leaderboard entries from a REST API, generating the GDScript class from your JSON payload gives you typed variables and a from_dict() factory method instantly — no manual key-by-key assignment.

Live Example: Player Data from Game Server

# Input JSON
{
  "player_id": "plr_9921",
  "username": "shadow_runner",
  "level": 42,
  "score": 184750,
  "is_premium": true,
  "last_seen": "2024-03-15T10:00:00Z"
}

# Generated GDScript
# Generated by TypeMorph — GDScript
class_name Root

var player_id: String = ""
var username: String = ""
var level: float = 0.0
var score: float = 0.0
var is_premium: bool = false
var last_seen: String = ""

static func from_dict(dict: Dictionary) -> Root:
  var instance = Root.new()
  if dict.has("player_id"):
    instance.player_id = dict["player_id"]
  if dict.has("username"):
    instance.username = dict["username"]
  if dict.has("level"):
    instance.level = dict["level"]
  if dict.has("score"):
    instance.score = dict["score"]
  if dict.has("is_premium"):
    instance.is_premium = dict["is_premium"]
  if dict.has("last_seen"):
    instance.last_seen = dict["last_seen"]
  return instance

Refined Class: int Types and HTTP Request

# PlayerData.gd — refine float → int for level/score
class_name PlayerData

var player_id: String = ""
var username: String = ""
var level: int = 0        # int not float for whole numbers
var score: int = 0        # same
var is_premium: bool = false
var last_seen: String = ""

static func from_dict(dict: Dictionary) -> PlayerData:
  var p = PlayerData.new()
  p.player_id   = dict.get("player_id", "")
  p.username    = dict.get("username", "")
  p.level       = int(dict.get("level", 0))      # explicit int cast
  p.score       = int(dict.get("score", 0))
  p.is_premium  = bool(dict.get("is_premium", false))
  p.last_seen   = dict.get("last_seen", "")
  return p

func to_dict() -> Dictionary:
  return {
    "player_id":  player_id,
    "username":   username,
    "level":      level,
    "score":      score,
    "is_premium": is_premium,
    "last_seen":  last_seen,
  }

Fetching JSON from an API in Godot 4

# GameAPI.gd — HTTP request autoload
extends Node

const BASE_URL = "https://api.mygame.com"

func fetch_player(player_id: String) -> PlayerData:
  var http = HTTPRequest.new()
  add_child(http)

  var error = http.request(BASE_URL + "/players/" + player_id)
  if error != OK:
    push_error("Request failed: " + str(error))
    return null

  # Await the request_completed signal
  var result = await http.request_completed

  http.queue_free()

  var response_code = result[1]
  var body: PackedByteArray = result[3]

  if response_code != 200:
    push_error("HTTP error: " + str(response_code))
    return null

  var json = JSON.new()
  var parse_error = json.parse(body.get_string_from_utf8())
  if parse_error != OK:
    push_error("JSON parse error: " + json.get_error_message())
    return null

  return PlayerData.from_dict(json.data)

# Usage in a scene
func _ready():
  var player = await GameAPI.fetch_player("plr_9921")
  if player:
    $UsernameLabel.text = player.username
    $LevelLabel.text = "Level " + str(player.level)

Loading JSON Config Files (no network)

# For level configs, item databases, etc. stored as .json files in res://
func load_level_config(level_id: int) -> Dictionary:
  var path = "res://data/levels/level_%d.json" % level_id
  var file = FileAccess.open(path, FileAccess.READ)
  if not file:
    push_error("Could not open: " + path)
    return {}

  var json_string = file.get_as_text()
  file.close()

  var json = JSON.new()
  if json.parse(json_string) != OK:
    push_error("JSON parse error in " + path)
    return {}

  return json.data

# Using the config
var config = load_level_config(3)
var enemy_count = int(config.get("enemy_count", 5))

Frequently Asked Questions

Why does the generator use float for integer JSON fields? JSON numbers are untyped — the generator uses float as a safe default since GDScript can parse any JSON number as float. Change level, score, and other whole-number fields to int and add an explicit cast: int(dict.get("level", 0)).

What's the difference between Godot 3 and Godot 4 JSON parsing? In Godot 3, you used JSON.parse(string).result. In Godot 4, create a JSON instance, call json.parse(string) (returns an error code), then read json.data. Alternatively, use JSON.parse_string(string) as a one-liner that returns the parsed data directly (or null on error).

Should I use class_name or keep the class anonymous? Use class_name PlayerData when the class is used across multiple scenes — it becomes globally available without preload(). Skip it for one-off inner classes or data classes only used in one script. Class names must be unique across the entire project.

Is my JSON sent to a server? No. TypeMorph runs entirely in your browser — none of your data leaves your machine.