JSON Loading Guide (5.1 GDScript Track)

Scope

This guide is for the GridBuilding/GridPlacement 5.1 GDScript track.

• 5.1 is Godot-native and not intended for headless/server JSON workflows.
• If you want JSON-driven configuration, the recommended approach is:
  • Parse JSON in your game-level code using Godot’s JSON APIs
  • Convert the decoded data into the plugin’s expected Resources (e.g., Placeables)
  • Then call into the plugin using those resources

For the 6.0 C# approach (including headless/back-end JSON pipelines), see:

• docs/6.0/Core/JSON_LOADING.md

Why JSON parsing is not part of the 5.1 plugin boundary

The 5.1 plugin is designed around Godot resources and scenes:

• .tres / .tscn under res://
• ResourceLoader as the canonical loader
• GBInjectorSystem as the canonical composition root

Adding a plugin-owned JSON loader introduces extra surface area (IO, error policy, schema drift) that is out of scope for the 5.1 legacy track.

Recommended pattern

1) Parse JSON in game code

Use Godot’s built-in JSON parsing.

Example sketch:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Game-level code (not inside the plugin)
func load_placeables_from_json(path: String) -> Array[Resource]:
    var text := FileAccess.get_file_as_string(path)
    if text.is_empty():
        return []

    var data: Variant = JSON.parse_string(text)
    if data == null:
        return []

    # Expect an array or dictionary depending on your schema
    # Convert into Placeable Resources next
    return _convert_to_placeable_resources(data)

2) Convert JSON data into Resources

Two common strategies:

• A) Reference existing .tres resources by path

  • JSON contains "placeable_path": "res://.../my_placeable.tres"
  • Game code loads it via ResourceLoader.load()

• B) Create Resources at runtime

  • JSON contains raw fields
  • Game code creates a new Resource instance and populates fields

Example for strategy A:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

func _convert_to_placeable_resources(data: Variant) -> Array[Resource]:
    var result: Array[Resource] = []
    if typeof(data) != TYPE_ARRAY:
        return result

    for entry in data:
        if typeof(entry) != TYPE_DICTIONARY:
            continue

        var p: String = entry.get("placeable_path", "")
        if p.is_empty():
            continue

        var r := ResourceLoader.load(p)
        if r != null:
            result.append(r)

    return result

3) Hand Resources to the plugin

Once you have Placeable (or equivalent) resources, pass them into your plugin entrypoints / registries.

This keeps:

• JSON schema concerns in your game
• resource identity + caching in Godot
• plugin runtime focused on placement behavior

Notes

• This guide intentionally avoids defining a strict JSON schema. Your game’s schema should match your content pipeline.
• If you need a formal schema + headless content build pipeline, follow the 6.0 approach via AssetLoader:
  • docs/6.0/Core/JSON_LOADING.md