{"id":101324,"plugin_id":"plugin_asdk_app_6ae4dce05e848191869076c72aec15cc","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-17T12:11:08.074Z","digest":"2b0417c77847be89be7d9fdd1844210db02fc5ad4c30fe22c8c59456a1d81202","against":null,"payload":{"description":"For Exekite-hosted Godot games only. File placement and structure for a multi-scene Godot project — entities/ vs scenes/ vs ui/, scene vs script vs Resource, when to extract a sub-scene, group tagging. Use when restructuring an existing project or when a new file's location is genuinely unclear.","included_files":[],"name":"scene-organization","skill_md_contents":"---\nname: scene-organization\ndescription: \"For Exekite-hosted Godot games only. File placement and structure for a multi-scene Godot project — entities/ vs scenes/ vs ui/, scene vs script vs Resource, when to extract a sub-scene, group tagging. Use when restructuring an existing project or when a new file's location is genuinely unclear.\"\n---\n\n# Scene organization\n\nVanilla Godot. The filesystem is the source of truth. There is no manifest above it.\n\n## Folder layout (canonical)\n\n```\nproject_root/\n├── project.godot                  # HARNESS-WRITTEN. You may not touch it.\n├── export_presets.cfg             # harness-written\n├── scenes/\n│   └── Main.tscn                  # THE ENTRY SCENE. run/main_scene points here.\n├── <anything>.gd                  # scripts live wherever you want them\n└── <anything>.tres                # typed Resource values, likewise\n```\n\n**The hosted authoring path rules are enforced.** `.godot/` and other\nplatform-managed/private paths are refused. Read the returned turn state\nrather than assuming a refusal rolled back the draft. (`.json` and `.md` are\nalso accepted suffixes.)\n\nWithin those rules, group however the game reads best. A conventional shape:\n\n```\nscenes/Main.tscn                   # required\nentities/<id>/<id>.gd + <id>.tscn  # one folder per entity kind\nentities/<id>/stats.tres           # typed values, when there are many\nui/<name>/<name>.gd + <name>.tscn  # HUD, pause menu, dialogs\n```\n\nThat is the shape the rest of this document assumes. `entities/` and `ui/` are\nordinary directories you create — nothing special about them beyond convention.\n\nWhen adding something, ask: **is this a thing the world has many of (entity), a place the player visits (scene), or an interface they read (ui)?**\n\n## Scene vs script vs resource — the decision tree\n\n```\nIs this thing INSTANTIABLE multiple times in the world?\n    ├── Yes → it's an entity. Make a .tscn under entities/<id>/.\n    │\n    └── No, is it a place/screen the player navigates to?\n            ├── Yes → it's a scene. Make a .tscn under scenes/<name>/ or ui/<name>/.\n            │\n            └── No, is it pure data (numbers, strings, references)?\n                    ├── Yes → it's a Resource. Make a class_name X extends Resource\n                    │         and a .tres file.\n                    │\n                    └── No → it's behavior on an existing thing. Edit the\n                              relevant script, or extract a child node.\n```\n\n## Entity scene shape\n\nA typical entity (`entities/coin/coin.tscn`):\n\n```\nCoin (Area2D, script: coin.gd)\n├── Sprite2D\n├── CollisionShape2D\n└── Sound (AudioStreamPlayer)\n```\n\nOr for the player (`entities/player/player.tscn`):\n\n```\nPlayer (CharacterBody2D, script: player.gd, groups: [\"player\"])\n├── Sprite2D\n├── CollisionShape2D\n├── Camera2D\n├── JumpSound (AudioStreamPlayer)\n├── LandSound (AudioStreamPlayer)\n└── HurtSound (AudioStreamPlayer)\n```\n\nThe root node owns the script. Children are atoms (visual, collision, audio). Nothing fancier than that until you genuinely need it.\n\n## Level/scene shape\n\nA level scene's root is usually a `Node2D` (or `Node` for non-spatial). The level instances entities and arranges them:\n\n```\nLevel1 (Node2D, script: level_1.gd)\n├── Background (TileMapLayer or Parallax2D)\n├── Terrain (TileMapLayer)\n├── Entities/\n│   ├── @Player.tscn             (instanced)\n│   ├── @Coin.tscn ×N            (instanced multiple times)\n│   └── @Flag.tscn               (instanced)\n├── Hazards/\n│   └── @Spike.tscn ×N\n└── HUD (CanvasLayer + Control nodes)\n```\n\nUse **scene instancing**: declare `[ext_resource type=\"PackedScene\" path=\"res://entities/coin/coin.tscn\" id=\"3_coin\"]` at the top of the level `.tscn` (and bump `load_steps`), then instance it with `[node name=\"Coin\" parent=\"Entities\" instance=ExtResource(\"3_coin\")]`. Don't inline-copy an entity's nodes into the level; you lose the link to the source scene.\n\n## When to extract a sub-scene\n\nExtract a scene when the thing repeats. If you're going to need 50 of them, it's a scene. If you're going to need 2, it's also probably a scene (linking is cheaper than duplicating).\n\nConversely, don't extract a scene that has exactly one instance and isn't reused — that's overhead. Inline it in its parent.\n\n## When to make a Resource\n\nYou're making a Resource when:\n\n- You want the values editable in the Inspector and saved as `.tres`.\n- The same shape (e.g. enemy stats) will exist with different values.\n\nSkip a Resource when there are 1–2 trivial fields. Inline `@export` on the script.\n\n## Groups\n\nUse Godot groups to tag entities the rest of the game queries:\n\n```gdscript\n# In .tscn or via script:\nadd_to_group(\"player\")\nadd_to_group(\"enemy\")\n\n# Querying:\nfor e in get_tree().get_nodes_in_group(\"enemy\"):\n    e.queue_free()\n```\n\nThe platformer's player is in the `\"player\"` group; coins check `body.is_in_group(\"player\")` instead of casting to a specific class. This keeps coupling loose.\n\n## Anti-patterns\n\n- One giant scene file with everything inline. If it has more than ~20 nodes, look for sub-scenes.\n- Entities under `scenes/`. Put entities under `entities/`; reserve `scenes/` for places.\n- Naming entities by their class (`CharacterBody2D.tscn`). Name them by what they are: `player.tscn`, `goblin.tscn`.\n- Referencing `res://assets/...` anywhere. There are no asset files; visuals and audio are generated in code, and a write into `assets/` is refused.\n- Making a Resource for every entity. The player has one because it has 10 tunables; the coin has none because it has 2.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}