{"id":101318,"plugin_id":"plugin_asdk_app_6ae4dce05e848191869076c72aec15cc","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-17T12:11:07.901Z","digest":"da653190e9c6e4429cd10eff3ea351e2f8a67d9d64f576565cffa967f081f430","against":null,"payload":{"description":"For Exekite-hosted Godot games only. GDScript house style — naming, type-hint policy, script section ordering, node-reference forms, signal-up/call-down. Use when a specific convention question arises (naming a signal, ordering sections, choosing $-path vs %unique-name access) or when reviewing GDScript for style drift.","included_files":[],"name":"gdscript-style","skill_md_contents":"---\nname: gdscript-style\ndescription: \"For Exekite-hosted Godot games only. GDScript house style — naming, type-hint policy, script section ordering, node-reference forms, signal-up/call-down. Use when a specific convention question arises (naming a signal, ordering sections, choosing $-path vs %unique-name access) or when reviewing GDScript for style drift.\"\n---\n\n# GDScript style\n\nGodot's idioms reward explicit typing and small, focused scripts. This is the house style for Exekite projects.\n\n## Naming\n\n| Thing | Style | Example |\n|---|---|---|\n| Class names (`class_name X`) | `PascalCase` | `PlayerStats`, `EnemyBehavior` |\n| Variables, functions, parameters | `snake_case` | `jump_velocity`, `apply_damage(amount)` |\n| Constants | `SCREAMING_SNAKE_CASE` | `MAX_LIVES`, `LEVEL_1_PATH` |\n| Signals | past-tense `snake_case` | `coins_changed`, `player_died`, `body_entered` |\n| Private fields/methods (convention only) | `_underscore_prefix` | `_coyote_t`, `_apply_gravity()` |\n| Node paths in scenes | `PascalCase` | `Sprite2D`, `JumpSound`, `CollisionShape2D` |\n\n## Type hints — always\n\n```gdscript\n# WRONG\nvar speed = 100\nfunc move(amount):\n    position.x += amount\n\n# RIGHT\nvar speed: float = 100.0\nfunc move(amount: float) -> void:\n    position.x += amount\n```\n\nWhy: explicit types catch errors at parse time (Godot's static checker is real), drive autocomplete, and double as documentation. The cost is one colon per declaration; pay it.\n\nFor locals, `:=` lets the type infer:\n\n```gdscript\nvar dir := Input.get_axis(\"ui_left\", \"ui_right\")  # inferred float — only the\n# pre-bound actions exist (ui_left/ui_right/ui_up/ui_down, ui_accept,\n# ui_cancel, pause, fire, interact)\nvar t := create_tween()                                # inferred Tween\n```\n\n### `:=` only works when the right-hand side has a known type\n\nThis is the single most common way an authored game fails to parse. When the\nexpression yields `Variant`, `:=` is a **parse error** — it does not quietly fall\nback to an untyped variable, and the script (plus every script that depends on\nit) fails to load:\n\n```\nParse Error: Cannot infer the type of \"f\" variable because the value doesn't have a set type.\n```\n\nThree sources of `Variant` produce almost all of these:\n\n```gdscript\n# 1. Indexing an UNTYPED array or dictionary\nvar notes = [523.25, 659.25]      # untyped Array\nvar f := notes[0]                 # WRONG — element type is Variant\nvar f: float = notes[0]           # RIGHT (or type the array: var notes: Array[float] = [...])\n\n# 2. A member of a loosely-typed node\nvar game := get_parent()          # inferred Node — `player` is not a Node member\nvar target := game.player.position    # WRONG — unknown member is Variant\nvar target: Vector2 = game.player.position  # RIGHT\n\n# 3. Anything returning Variant\nvar v := ProjectSettings.get_setting(\"x\")   # WRONG\nvar v: int = ProjectSettings.get_setting(\"x\")  # RIGHT\n```\n\nRule of thumb: **type your array and dictionary literals** (`var melody: Array[float] = [...]`),\nand the moment a value comes out of a container, a `get_parent()`, or an untyped\nAPI, write the type explicitly instead of `:=`.\n\n## Script structure — top-down ordering\n\nThe convention:\n\n1. `class_name` (if any)\n2. `extends`\n3. Top-level docstring (`##` lines)\n4. Signals\n5. Enums\n6. Constants\n7. `@export` vars (Inspector-visible tunables)\n8. `@onready` vars\n9. Internal state vars (`_underscore_prefixed`)\n10. `_ready`, `_enter_tree`, `_exit_tree`\n11. `_process`, `_physics_process`, `_input`, `_unhandled_input`\n12. Public methods\n13. Private methods (`_underscore_prefixed`)\n14. Signal handlers (`_on_<source>_<signal>`)\n\nYou don't have to be religious about it, but be consistent within a file.\n\n## Node references — two good ways, no bad ways\n\n```gdscript\n# (a) @onready + relative path — for stable, scene-internal nodes\n@onready var sprite: Sprite2D = $Sprite2D\n@onready var hp_bar: ProgressBar = $UI/HPBar\n\n# (b) @onready + % unique name — for nodes whose path may move within a scene\n#     (requires `unique_name_in_owner = true` on that node's [node] entry in\n#     the .tscn — without it, %Name resolves to null at runtime)\n@onready var camera: Camera2D = %Camera\n```\n\nAssetRegistry-guarded art in a Python-born game is the `generated-media-wiring` skill's domain — do not invent `/root/` lookups; freeform games have no autoloads.\n\nAvoid `get_node(\"Some/Long/Brittle/Path\")` with string concatenation. If a path needs to be dynamic, use `find_child(name, true, false)`, but interrogate whether the design needs to be that loose first.\n\n## Signal-up, call-down\n\nThe community rule: a child node never reaches into a parent or sibling and calls a method on them. Instead, the child **emits** a signal; the parent **listens** and routes.\n\n```gdscript\n# Coin (Area2D, child of level)\nsignal coin_collected(amount: int)\nfunc _on_body_entered(body: Node) -> void:\n    if body.is_in_group(\"player\"):\n        coin_collected.emit(1)\n\n# Level (parent — owns the score, since freeform games keep cross-scene\n# state on the root game script, not on an autoload)\nfunc _ready() -> void:\n    for coin in $Coins.get_children():\n        coin.coin_collected.connect(_on_coin_collected)\n\nfunc _on_coin_collected(amount: int) -> void:\n    score += amount\n    hud.set_score(score)\n```\n\nWhen that's overkill (a direct parent→child call), call down directly — the rule is signals UP, calls DOWN.\n\n## Returns: explicit `-> void` over implicit\n\n```gdscript\n# Acceptable but discouraged\nfunc _ready():\n    pass\n\n# Idiomatic\nfunc _ready() -> void:\n    pass\n```\n\nFunctions that return values: type the return.\n\n```gdscript\nfunc clamp_health(amount: int) -> int:\n    return clampi(amount, 0, max_health)\n```\n\n## Comments\n\nLead with `##` (double-hash) for class/method documentation that the editor surfaces in tooltips. Use `#` for inline.\n\n```gdscript\n## Player tunables. Edit values in the inspector (or any .tres instance);\n## the player controller reads them every physics tick.\nclass_name PlayerStats\nextends Resource\n```\n\nDon't comment things that the type and name already say. `# decreases hp` above `func take_damage(amount: int) -> void:` is dead weight.\n\n## Anti-patterns\n\n- Untyped function parameters or return types in shipped code.\n- `:=` on a value whose type Godot cannot infer — an untyped array/dictionary element, an unknown member on a `get_parent()` result, or any `Variant`-returning call. It is a parse error, not a fallback.\n- `get_node()` with a long path string instead of `$RelativePath` or `%UniqueName`.\n- Side effects at the top of the file (lines outside `func`s) — initialization belongs in `_ready` or `_init`.\n- `_process(delta)` doing physics-affecting work — that belongs in `_physics_process(delta)`.\n- 200-line scripts with no class boundary. If you can name a slice \"this is what the X system does\", it's probably a separate script.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}