Skip to content

Add gdscript and godot package definitions - #7

Merged
TeeJS merged 1 commit into
mainfrom
add-gdscript-godot-packages
Sep 5, 2026
Merged

Add gdscript and godot package definitions#7
TeeJS merged 1 commit into
mainfrom
add-gdscript-godot-packages

Conversation

@TeeJS

@TeeJS TeeJS commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Add GDScript and Godot Engine package definitions

Adds two registry definitions built from godotengine/godot-docs:

  • registry/gdscript/gdscript.yaml — the GDScript language
  • registry/godot/godot.yaml — the Godot engine: full class reference + tutorials

Both use the self-named-directory convention the registry README prescribes for projects
not distributed by a package manager, alongside registry/python/python.yaml and
registry/java/java.yaml.

Build results

Built at godot-docs commit 6d86d7c7f3b8f4f56c71e113022d72fe80b2c84d
(branch stable, 2026-08-05, = Godot 4.7):

definition docs_path files sections tokens skipped size
gdscript/gdscript tutorials/scripting/gdscript 9 129 60,921 0 0.45 MB
godot/godot (whole repo) 1,604 14,488 8,136,611 0 48.03 MB

Zero skipped files in both. .rst is already a supported input format, so no new parsing
is required. Both definitions were validated by running the repository's own
loadDefinition() and listDefinitions() — including the whole-tree scan, since one bad
definition fails the nightly publish for every other package.

Why gdscript is scoped narrowly

tutorials/scripting/gdscript yields 129 sections, which is below the README's "a few
hundred" guideline, so it is worth explaining why that is deliberate rather than a
misconfigured docs_path.

The obvious wider path, tutorials/scripting, yields 515 sections — but they break down as:

area sections
c_sharp/ 208 (40%)
gdscript/ 129 (25%)
scripting/ root 97
cpp/ 41
debug/ 40

C# is the largest block in what would ship as a GDScript package, and it wins the most
important queries. Top-5 results from that build, ranked exactly as search.ts ranks them
(bm25(chunks_fts, 5.0, 10.0, 1.0) * -1, ORDER BY score DESC, after buildQuery()):

Since git sources have no exclude_paths (only zip sources do), the C# and C++ subtrees
cannot be pruned from tutorials/scripting. Narrowing the path is the only way to get a
GDScript package that returns GDScript. The same queries against the narrow build return
gdscript_basics: Signals ×3, gdscript_exports ×4, and static_typing ×4 — every top hit
on target.

One further consequence of the narrow scope, stated plainly because a reviewer will hit it:
when a query matches a built-in function name, the gdscript package returns
lexically-plausible but topically-wrong results rather than nothing, because those words
appear incidentally in tutorial prose.

query gdscript package returns actually documented in
preload gdscript_basics: Keywords, Classes classes/class_@gdscript.rst
range gdscript_exports: Limiting editor input ranges classes/class_@gdscript.rst
push_error static_typing: How to use static typing classes/class_@globalscope.rst
get_node gdscript_styleguide: Static typing classes/class_node.rst
inst (no results) classes/class_@gdscript.rst

All five resolve correctly in the godot package. This is intended routing rather than a
defect — classes/ is unreachable from any tutorial path — but it is why the gdscript
description names the built-ins explicitly and points at the godot package for them,
instead of only mentioning "engine APIs".

Everything the narrow path omits (autoloads, resources, groups, the scene tree,
overridable functions, debugging, multiplayer RPC) is covered by the godot package,
which also carries class_@gdscript.rst and class_@globalscope.rst — the built-in
functions (preload, load, assert, range, str) that live in classes/ and are
unreachable from any tutorial path. Each definition's description points at the other so
an agent can route between them.

Notes for reviewers

  • ref: stablegodot-docs has no git tags at all, and no ReadTheDocs htmlzip
    archives are published (all such URLs 404), so neither the tag-pattern nor the
    versioned-by-zip shape applies. The stable branch tracks the current Godot release and
    advances on its own, and source_commit is populated so skip-if-unchanged works.
  • Path separators — building on Windows produces doc_path values with backslashes
    (tutorials\scripting\...). That is a local artifact of readLocalDocsFiles on Windows,
    not a problem with these definitions; Linux CI produces forward slashes. Please don't
    "fix" the YAML paths for it.
  • Unrelated pre-existing Windows issue (not introduced here, no fix included) — running
    listDefinitions() on Windows throws
    Definition name "@apollo/client" doesn't match filename "@apollo\client.yaml", because
    loadDefinition() compares a relative() path against a /-joined name. It reproduces
    on main with these definitions removed, so it is not caused by this PR and does not
    affect Linux CI. Flagging it rather than fixing it here to keep this PR to one concern; a
    split(sep).join("/") on the derived name would resolve it.
  • Sizegodot is 48.03 MB, against the client's 512 MB DEFAULT_MAX_DOWNLOAD_BYTES
    and fetched on demand. A classes-only variant was measured (10,960 sections, 38.8 MB);
    it saves 9 MB and loses every tutorial, so it was rejected.

Attribution

godotengine/godot-docs is licensed CC-BY 3.0 Unported (verified from its
LICENSE.txt). Both definitions carry repository: pointing at the upstream repo.


Relationship to the upstream PR

The same two files are also proposed upstream as
neuledge/context#133. This PR is
independent of it: merging here puts the definitions in this fork's registry/, which is
what the fork's own registry-update workflow reads, so the packages can be built and
published to this fork's REGISTRY_SERVER_URL without waiting on upstream review.

The file contents on both branches are byte-identical (verified by git hash-object), so
if upstream merges neuledge#133 unchanged, a later sync from upstream/main resolves silently —
both sides added the same paths with the same content. If upstream requests changes during
review, the sync becomes an add/add conflict resolved by taking upstream's version.

After merging, the packages are published by running the Registry Update workflow
(workflow_dispatch) rather than waiting for its 06:00 UTC schedule. Note that the
scheduled run passes --since 2; unversioned definitions like these bypass that filter
(version-check.ts:48-61 returns a single latest version before --since is applied),
so no workflow change is needed.

Two unversioned definitions built from godotengine/godot-docs at ref
stable (Godot 4.7):

  gdscript/gdscript  docs_path tutorials/scripting/gdscript
                     9 files, 129 sections, 60,921 tokens, 0 skipped
  godot/godot        whole repo
                     1,604 files, 14,488 sections, 8,136,611 tokens, 0 skipped

Built at godot-docs 6d86d7c7f3b8f4f56c71e113022d72fe80b2c84d and
reproduced independently three times across node 22/24 and context
1.2.4/1.2.5 with identical file, section and token counts.

gdscript is scoped to the GDScript subtree rather than to
tutorials/scripting because the wider path is 40% C# by section count
(208 of 515), and C# wins the ranking for the most common lookups --
under the product's own bm25 weights, none of the top five results for
"signal" is GDScript. Git sources have no exclude_paths, so narrowing
the path is the only way to get a GDScript package that returns
GDScript. Everything the narrow path omits, including the @GDscript and
@globalscope built-ins in classes/, is covered by the godot package, and
each description points at the other.

godot-docs is licensed CC-BY 3.0 Unported.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWBBpEmsr5oyEhamfREYNx
@TeeJS
TeeJS merged commit 6bd42ed into main Sep 5, 2026
3 checks passed
TeeJS added a commit that referenced this pull request Sep 5, 2026
Two unversioned definitions built from godotengine/godot-docs at ref
stable (Godot 4.7):

  gdscript/gdscript  docs_path tutorials/scripting/gdscript
                     9 files, 129 sections, 60,921 tokens, 0 skipped
  godot/godot        whole repo
                     1,604 files, 14,488 sections, 8,136,611 tokens, 0 skipped

Built at godot-docs 6d86d7c7f3b8f4f56c71e113022d72fe80b2c84d and
reproduced independently three times across node 22/24 and context
1.2.4/1.2.5 with identical file, section and token counts.

gdscript is scoped to the GDScript subtree rather than to
tutorials/scripting because the wider path is 40% C# by section count
(208 of 515), and C# wins the ranking for the most common lookups --
under the product's own bm25 weights, none of the top five results for
"signal" is GDScript. Git sources have no exclude_paths, so narrowing
the path is the only way to get a GDScript package that returns
GDScript. Everything the narrow path omits, including the @GDscript and
@globalscope built-ins in classes/, is covered by the godot package, and
each description points at the other.

godot-docs is licensed CC-BY 3.0 Unported.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@TeeJS
TeeJS deleted the add-gdscript-godot-packages branch September 5, 2026 02:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant