AgentFoundrySign in ↗
← All examples

asset contracts

Godot .tscn and .tres parser and linter

Parse Godot 4 text scenes and resources and find what fails or silently vanishes on load: missing resource files, unknown or forward resource ids, missing node parents, repeated sibling names, untyped nodes, broken connections, several roots, syntax and format errors.

What this component contains

  • ATTRIBUTION.md
  • LICENSE
  • README.md
  • asset_report.py
  • component.json
  • fixtures/project/materials/bad_brass_missing_texture.tres
  • fixtures/project/materials/wood.tres
  • fixtures/project/project.godot
  • fixtures/project/scenes/bad_connection.tscn
  • fixtures/project/scenes/bad_duplicate_sibling.tscn
  • fixtures/project/scenes/bad_forward_sub_resource.tscn
  • fixtures/project/scenes/bad_future_format.tscn
  • fixtures/project/scenes/bad_missing_material.tscn
  • fixtures/project/scenes/bad_parent_path.tscn
  • fixtures/project/scenes/bad_syntax.tscn
  • fixtures/project/scenes/bad_two_roots.tscn
  • fixtures/project/scenes/bad_unknown_ext_id.tscn
  • fixtures/project/scenes/bad_unknown_sub_id.tscn
  • fixtures/project/scenes/bad_untyped_node.tscn
  • fixtures/project/scenes/door.tscn
  • fixtures/project/scenes/godot3_door.tscn
  • fixtures/project/scenes/room.tscn
  • fixtures/project/scripts/door_controller.gd
  • gltfio.py
  • godot_scene_linter.py
  • pngio.py
  • schema_lite.py
  • test_godot_scene_linter.py
  • test_package.py
  • verification/native.json

How it works

Entry points
parse, node_paths, lint, run, main
Proves
The file parses; every res:// external resource exists under the project root; every ExtResource and SubResource id is declared, sub-resources before their first use; the scene has one root, every node a known parent (including nodes of instanced scenes), a type or an instance, and a unique name among its siblings; every connection joins existing nodes.
Does not prove
That property values are valid for their class, that scripts compile, that signals and methods exist, or that uid:// references resolve (the uid cache is not read).
Catches
file_unreadable, syntax_invalid, header_invalid, format_unsupported, ext_resource_invalid, ext_resource_id_repeated, ext_resource_missing_file, ext_resource_reference_unknown and 9 more

Recorded checks

godot godot 4.7.2.stable.official.ed1daf0bf

  • checker_matches_contract
  • godot_loads_known_good_files_as_parsed
  • each_known_wrong_file_has_a_visible_effect_in_godot

Limits to consider

Resources are checked by res:// path only; uid-only references are not resolved. Property values are scanned for ExtResource and SubResource references but not type-checked. Signals and methods named by connections are not checked. Nodes inside instanced scenes are found by parsing those scenes (eight levels deep at most). Godot 3 scenes (format 2) are parsed with a warning, because Godot 4.7 converts their class names on load.