Godot Game Loop Harvest

Script Catalog (MANDATORY by path)

Setup (short)

1. Author HarvestResourceData / HarvestToolData .tres (tool enum + tier, yield range, optional drop scene).
2. Attach harvestable_node.gd to StaticBody3D; assign data + mesh_to_shake; keep interaction on Layer 1.
3. Autoload harvest_respawn_manager.gd as HarvestRespawnManager when world persistence is required.

Hit path

Raycast/interact → apply_hit(tool_data: HarvestToolData):

if collider is HarvestableNode:
    collider.apply_hit(player_tool)

NEVER Do

• NEVER use float for accumulated harvest counts — use int.
• NEVER gather rates in _process without delta — framerate-scales economy.
• NEVER trust OS.get_ticks_msec() for offline progress — use Time.get_unix_time_from_system().
• NEVER check tool type via free-form strings — use HarvestToolData.ToolType / StringName enums (see scripts).
• NEVER mutate shared Resource templates — duplicate(true) before runtime durability/health mutation.
• NEVER queue_free() before VFX/SFX finish — hide mesh, swap collision layer, free after juice.
• NEVER skip saving UNIX timestamp on exit — offline gains depend on it.
• NEVER couple harvest logic to UI counters — signals only.
• NEVER scale collision shapes non-uniformly — edit shape resource sizes.

Vein proc-gen (noise)

Use FastNoiseLite thresholds for organic clusters; spawn HarvestableNode instances where noise.get_noise_2dv(pos) > threshold. Persist depleted IDs via respawn manager — do not re-roll veins every load without a seed.

Tool durability

Keep durability on HarvestToolData (Resource), not the player node. Emit durability/break signals from the tool Resource after successful hits.

MANDATORY for offline UNIX math, worker-thread batching, popup pools, and vein proc-gen depth: harvest-elite-patterns.md. Do NOT Load when hit path + respawn manager suffice.

Reference

Progressive disclosure: Skim Official Documentation only for the APIs you are implementing (Resources, StaticBody3D hits, signals, timers, save/offline time). Open Related Skills when wiring inventory, autoloads, raycasts, or economy balance—do not preload the whole lattice.

Official Documentation

• Resources — Author HarvestResourceData / HarvestToolData as shareable .tres assets so designers tune health, yield ranges, and tool gates without editing harvest scripts.
• Resource — Call duplicate(true) before mutating runtime harvest/tool state so one node’s depletion or durability cannot rewrite the shared template Resource.
• GDScript exports — @export / @export_group power Inspector-authored tool tiers, yield ranges, respawn times, and drop scenes on harvest data Resources.
• Using signals — Emit harvested, took_damage, and interaction_failed so inventory, HUD bars, and feedback UI subscribe without coupling to HarvestableNode internals.
• StaticBody3D — World harvestables are static colliders players query/hit; keep them on an interaction layer and move to an inactive layer while depleted.
• Collision shapes (3D) — Size shape resources directly; non-uniform scale on collision shapes breaks hit tests for pickaxes/axes against trees and ore nodes.
• Idle and Physics Processing — Multiply continuous gather rates by delta (prefer _physics_process for fixed-step economy ticks) so harvest speed is not framerate-dependent.
• Time — Persist Time.get_unix_time_from_system() for offline gains; do not use OS.get_ticks_msec() / uptime for real-world absence math.
• Saving games — Persist inventory counts, depleted-node IDs, and absolute respawn/offline timestamps with the rest of progression data.
• FileAccess — Interval autosave writes JSON (or binary) under user:// via FileAccess.open so harvest progress survives crashes between manual saves.
• Tween — Hit “juice” shakes use short property tweens on the mesh child without allocating disposable animation players per strike.
• Singletons (Autoload) — Register HarvestRespawnManager as an Autoload so scattered harvestables resolve /root/HarvestRespawnManager for world-scale depletion persistence.