puzzle-quest/CLAUDE.md

Puzzle Quest

Hidden-object game built with Godot 4.6 (single renderer: Forward+). Branched from a Godot 3.3 codebase — migration is recent, expect leftover Godot-3-isms to occasionally surface.

Run

godot --editor   # open project in the editor
godot            # run the main scene (scenes/Main.tscn)

The system package godot (Arch extra/godot) is the project's Godot. There is no in-repo Godot binary.

Architecture

Autoloads (declared in project.godot [autoload], loaded in this order):

Name	Source	Role
Loading	scenes/UI/loading/Loading.tscn	Full-screen transition overlay (BG + animated border + progress)
Global	scripts/Global.gd	Async scene loader (goto_scene(path)) + database reference
Setting	scripts/Setting.gd	Reads/writes the settings table; applies locale/resolution/fullscreen
Event	scripts/Event.gd	Static handlers connected to scene buttons (Warcraft / Home / reset / back)
GlobalAnimation	scripts/Animation.gd	Tween-based dissolve + HUD slide/warning animations

Database (scripts/Database.gd)

• Plain JSON at db/ahog.json. Three tables: settings, levels, scenes.
• On Android the file is copied once to user://database.json and written there (game saves modify lock state per item).
• Global.database is a Database.DB instance exposing get_table_by_name(name) and save_db(). Each Table exposes get_data_at_row_idx(row_id), edit_data(prop_id, row_id, value), m_rows_count, get_data_by_prop_name_and_data(prop_name, value), get_dictionary_by_prop_name_and_data(prop_name, value).
• db/M*.gd are typed accessors (MBase / MScene / MLevel / MSetting) that read rows via the API above — extend these, not the JSON shape directly.

Scene transitions (Global.goto_scene(path))

Uses ResourceLoader.load_threaded_request + load_threaded_get_status + load_threaded_get (Godot 4 API; the original load_interactive/poll() was removed). The Loading overlay (autoload) plays BorderAnim while the new scene loads in a background thread; Event._loading_is_started/finished flip Global.loaded so the poll only runs once the entry animation has set the boolean. Don't call current_scene.queue_free() outside this function — it will leak the resource and break the loader state.

Levels.tscn / level scenes

scenes/levels/Levels.tscn is the shared shell; concrete levels (warcraft/WarCraft.tscn, home/Home.tscn) inherit from it. Each scene has a HiddenObjectsItems/<Item> MeshInstance3D with an Area3D collision shape; clicking it triggers Levels._check_collider → _start_dissolve(name) → GlobalAnimation.start_dissolve(mesh, material) which runs the dissolve shader on material.dissolve_amount.

The runtime hidden-object list lives under scenes/levels/parts/ListObjects.tscn and is populated dynamically from the scenes table for the current Global.current_scene_int.

Migration notes (Godot 3 → 4)

The conversion is mostly done but a few classes of mistake keep surfacing because godot --convert-3to4 does not handle them:

• Label: align/valign → horizontal_alignment/vertical_alignment.
• Button: pressed (property) → button_pressed; set_pressed() → assignment to button_pressed. The pressed signal still exists.
• ScrollContainer: scroll_horizontal_enabled = false → horizontal_scroll_mode = 0 (and same for vertical). ScrollContainer also ships a non-empty default panel style in Godot 4 — set theme_override_styles/panel = StyleBoxEmpty if you need transparency.
• TextureRect / TextureButton: expand = true → expand_mode = 1. stretch_mode enum values shifted down by 1 between 3 and 4 (the deprecated "Scale on Expand" at index 0 was removed): G3's Tile (2) is G4's Tile (1), G3's Keep (3) is G4's Keep (2), etc.
• Environment: background_mode enum changed (G3 3=Sky → G4 2=Sky; G4 3 is Canvas which renders black). background_sky → sky; background_energy → background_energy_multiplier; fog_color → fog_light_color; fog_height_min → fog_height; fog_mode = 1 (Depth) needed to keep fog_depth_* semantics, otherwise Godot 4 falls back to dense fog_density exponential fog.
• AnimationPlayer: add_animation(name, anim) removed — go through get_animation_library("") (create one with add_animation_library("") if it returns null) and call lib.add_animation(name, anim).
• Tween: no longer a Node — call create_tween() from any Node and use tween.tween_method(...). Delete any [node type="Tween"] from older .tscn files (the loader will crash otherwise).
• PhysicsRayQuery: space_state.intersect_ray(from, to, ...) → PhysicsRayQueryParameters3D.create(from, to), set fields, then space_state.intersect_ray(query).
• PackedScene.instance() → instantiate().
• String / cast operators: String(x) constructor doesn't exist — use str(x). x as int/String/bool does not parse strings — use int(s), str(x), bool(int(s)).
• Internationalization: project setting is [internationalization] locale/translations=..., not [locale] translations=.... Locale codes must match .po filenames exactly (fr.po → "fr"; G3-style fr_FR no longer auto-falls-back).
• Inherited scenes: nodes from an instanced child scene need layout_mode = 1 + anchors_preset = 15 explicitly set in the parent scene file, otherwise Godot 4 treats them as Position-mode and zeroes the anchors. Watch for stale per-Label layout_mode = 0 / anchor_right = 0 overrides in Main.tscn-style parent scenes.

Plugins

• addons/lod/ — Calinou's Level-of-Detail plugin (Spatial / OmniLight / SpotLight / Particles → 3D variants). Class declarations use the Godot 4 form (@icon("...") class_name X + extends Node3D separately).
• addons/godot_db_manager/ — removed during migration. Don't restore it; it relies on WindowDialog/Tabs/PopupPanel which were dropped in Godot 4. The replacement is scripts/Database.gd (see above).

Custom shaders / materials

Drop-in shaders live in .material resources (binary RSCC format) next to each prop. scripts/migrate_shaders.gd is a one-shot tool that walks assets/ and rewrites the embedded shader code (Godot 3 → 4 keyword renames: depth_draw_alpha_prepass, hint_color, NORMALMAP). Re-run it with godot --headless --script scripts/migrate_shaders.gd after adding new materials authored in Godot 3.

assets/fonts/text_outline.material is a VisualShader graph from Godot 3 that doesn't connect cleanly in 4 (out-of-bounds p_from_port errors, COLOR never written). It has been detached from the Summary menu labels; re-author it with Godot 4's built-in theme_override_constants/outline_size

• theme_override_colors/font_outline_color instead.

Known visual issues to revisit

• Baked lightmap is gone. scenes/levels/warcraft/WarCraft.lmbake is in Godot 3's binary format (incompatible). The LightmapGI node still exists in WarCraft.tscn but its light_data reference is cleared. Open the scene in the editor and re-bake (Scene → Bake Lightmaps).
• assets/ui/themes/tab_select/UI-level-btn-shadow.png is 83% opaque black with feathered edges (a drop-shadow texture). In Godot 4 it renders stretched and opaque, which looked like a black square below each level tile, so its BackgroundTile TextureRect is currently visible = false. Replace with a proper 9-patch / shader if the shadow effect is wanted.
• developers/aurelien/ is a sandbox — files there (ui_scrolls.tscn, ui_tile.tscn, CheckLightmap.tscn) still use Godot-3 property names in places. Not on the main flow, low priority.

CI

Gitea Actions workflow at .gitea/workflows/build.yml, documented in .gitea/workflows/README.md. Three jobs: GDScript validation (godot --headless --import + error grep), desktop matrix (Windows / Linux / macOS), and Android. Build only — no Butler / itch.io deploy currently wired (channels used historically were dev-crea/ahog:windows|android|linux|mac). Drone pipeline removed.

Branches: default dev, releases from main. Long-running migration work on feature/godot-migration.

Conventions

• Don't commit db/ahog.json runtime mutations (lock progress saved during play). The README documents using git update-index --skip-worktree but the cleaner alternative is just to git checkout db/ahog.json before staging.
• android/, .godot/, and releases/ are in .gitignore. The .import sidecars next to assets are committed (they carry the stable UIDs Godot 4 generates).
• Commit messages: imperative, English, explain the why (especially for migration commits — the next person reading the diff won't have the Godot 3 context).